Error Handling

The Evalyo API uses standard HTTP status codes together with a structured JSON error body.

Error format

Every error returns a JSON object with the following fields:

Typical error body

The code field is a machine-readable constant, ideal for handling errors programmatically in your code.

HTTP codes

Code	Description
`200 OK`	Request succeeded.
`201 Created`	Resource created successfully.
`400 Bad Request`	Missing or invalid parameters. Check the request body.
`401 Unauthorized`	API key missing, invalid, or revoked.
`403 Forbidden`	Valid API key but insufficient scope for this resource.
`404 Not Found`	Resource not found. Check the identifier.
`409 Conflict`	Data conflict (e.g. email already in use).
`422 Unprocessable Entity`	Semantically invalid data (e.g. a past date).
`429 Too Many Requests`	Rate limit reached. See the Retry-After headers.
`500 Internal Server Error`	Internal error. Retry after a few seconds.

Business errors

Evalyo-specific codes, returned in the error.code field:

Code	Description
`INSUFFICIENT_CREDITS`	Interview quota exhausted. Top up from the Billing page.
`INTERVIEW_ALREADY_COMPLETED`	The interview has already been completed and cannot be restarted.
`CANDIDATE_NOT_IN_CAMPAIGN`	The candidate does not belong to this recruitment process.
`TEST_ALREADY_ASSIGNED`	This test is already assigned to this candidate.
`JOB_CLOSED`	The job is closed and no interview can be created for it.

Frequently asked questions

Network errors have no JSON body (connection refused, timeout). API errors always return an { error: { code, message } } object with an HTTP code >= 400.

Read the Retry-After header in the response. It tells you how many seconds to wait before retrying. Implement exponential backoff for critical requests.

Yes, 500/503 errors are usually transient. Retry with exponential backoff (e.g. 1s, 2s, 4s). If the error persists for more than 5 minutes, contact support.

Catch the INSUFFICIENT_CREDITS code and redirect the user to the billing page, or alert your team to top up the credits.