Errors & troubleshooting

Interpret API failures, correct requests, and collect useful diagnostic information for support.

Use the HTTP status and error details together. Keep the response's X-Request-ID when contacting support; never send your API secret or a signed file URL.

Status	What to check	What to do
`400`	Required fields, query filters, IDs, enums and validation messages	Correct the request; repeating unchanged input will not help
`401`	Missing, invalid, expired or revoked credential	Check the Bearer header and credential status
`402`	Candidate/resume content restricted by storage capacity	Review your account's resume capacity; an API add-on does not bypass content restrictions
`403`	Required scopes or account API access	Ask an authorized account administrator to check access and credential permissions
`404`	ID is missing, deleted or not accessible to this account	Confirm the ID using the appropriate list endpoint
`409`	Job approval, active-job capacity, or idempotency conflict	Resolve the reported cause; do not blindly change the idempotency key
`429`	Minute, daily, monthly, concurrency or shared infrastructure limit	Respect `Retry-After` and reduce concurrency
`500`	Unexpected server failure	Keep the request ID; retry with bounded backoff, preserving the original idempotency key for writes
`503`	API authorization or quota service temporarily unavailable	Respect `Retry-After` when present; retry with bounded backoff

Understanding the error body

Structured route failures use application/problem+json. Read the response Content-Type before parsing, because earlier infrastructure responses can have a different format. Fields can include type, title, status, detail, instance, errors, code and requestId. Optional fields vary by failure; not every error has a machine code.

Common error messages and resolutions:

Message	Resolution
`description must contain at least 100 words`	Supply a complete job description; HTML markup does not count
`minimumExperience must not exceed maximumExperience`	Correct the experience bounds (years)
`API credential does not grant the required scope`	Check the scope listed by the endpoint; job creation requires `jobs.write`, and later lifecycle changes require `jobs.status.write`
`Customer API is not available for this account`	Check active plan or API add-on access
`Customer API is not enabled for this account`	Check account API access or contact support
`API credential is invalid`	Check the secret and credential expiry/revocation

Request tracing

Record X-Request-ID, the HTTP method, endpoint, timestamp and status. X-API-Contract identifies the response-envelope contract. Remove personal candidate data and credentials from any example you share with support.

Was this helpful?

Still need help? Ask the team