Troubleshooting

401 Unauthorized

Possible causes:

• The Bearer token is missing from the Authorization header
• The token is expired or invalid
• Sandbox credentials used against the production endpoint (or vice versa)

Solution:

Call POST /api/v1/auth/token with your Client ID and Client Secret to obtain a fresh token. Make sure you are using the correct environment’s credentials (sandbox vs. production). See the Authentication page.

400 Bad Request — validation error on submission

Common field validation failures:

• firstName or surname is blank or exceeds 50 characters
• email does not match the pattern name@domain.tld
• phone contains invalid characters (only digits, spaces, +, -, (, ), . are allowed)
• recruitmentId is missing
• gdprNotice is missing
• gdprNotice.validTo is in the past (INVALID_GDPR_VALID_TO)
• gdprNotice.validTo is supplied without gdprNotice.consentText (INVALID_GDPR_CONSENT_TEXT)

Solution: Review the error message in the response body and correct the corresponding field in your request.

422 Unprocessable Entity — invalid recruitment

The recruitmentId exists but is not active or does not belong to your company.

Solution: Use the ID of an active recruitment that belongs to your company.

429 Too Many Requests

You have exceeded the per-company rate limit of 50 requests per minute.

Solution: Reduce the frequency of your requests and implement exponential backoff with retry logic in your integration.

Too many attachments

The API returns 400 TOO_MANY_ATTACHMENTS if the attachments array contains more than 5 items.

Solution: Split the submission or reduce the number of attachments to 5 or fewer. The gdprNotice.consentText document does not count towards this limit.

Attachment too large

Each attachment (including GDPR documents) must not exceed 10 MB. If an attachment exceeds this limit, the request will be rejected.

Solution: Compress or reduce the file size before encoding it as base64.

Status stuck in PROCESSING

The GET /api/v1/candidate-reactions/{requestUuid} endpoint returns PROCESSING and does not transition to COMPLETED or FAILED.

Possible causes:

• Normal: processing can take a few seconds. Poll again after a short delay.
• Abnormal: an internal error occurred without updating the status record.

Solution: If the status does not change after several minutes, contact support with the requestUuid for investigation.