Errors and rate limits
Errors come back as JSON with an error message and, on most routes, a code you can branch on. The status tells you what to do: fix the key for 401, add a scope for 403, fix the request for 400 or 422, and wait for 429. Each key is limited to a number of requests a minute.
Reference · Last checked against the product on
Error shape
{
"error": "This needs a human-scoped key (decisions:human).",
"code": "HUMAN_REQUIRED"
}Branch on code where it is present and show error to people. Validation errors on the jobs, webhooks, job goal and bulk invitation routes also include a details object listing the fields that failed.
Status codes
| Status | Code | When |
|---|---|---|
| 200 | Success. Creating a job or a webhook endpoint answers 201. | |
| 400 | The body is not valid JSON or fails validation on the jobs, candidates, webhooks or bulk invitation routes. | |
| 401 | The key is missing, wrong or revoked, or its organisation is not active. | |
| 403 | FORBIDDEN | The key lacks a scope the call needs. The message names it. |
| 403 | HUMAN_REQUIRED | A move to a human-only stage without decisions:human. Approving or overriding a proposal without it answers 403 with no code. |
| 404 | NOT_FOUND | No such route, or the application, job or proposal is not in your organisation. A proposal that is no longer open answers the same way. |
| 405 | METHOD_NOT_ALLOWED | A GET sent to the MCP server, which answers POST only. |
| 409 | INVALID_TRANSITION | The application cannot move from its current stage to the one you asked for, or it is already there. |
| 409 | CONFLICT | The application changed while the move was applied. Read it again and retry. |
| 409 | NO_INTERVIEW | A scorecard was filed for an application with no interview yet. |
| 409 | NO_INVITATION | An offer draft was asked for on an application with no invitation. |
| 409 | NO_PANEL | A schedule proposal was approved on a job with no default panel. |
| 409 | Bulk invitations: the job is a draft or closed. | |
| 409 | REASON_REQUIRED | An override used a reason code that is not one of the accepted codes. |
| 409 | INVALID | An approved proposal could not be applied, for example because the stage changed. |
| 422 | INVALID | The fields failed validation. The message lists each field and the problem. |
| 422 | REASON_REQUIRED | An override was sent with no reason code at all. |
| 422 | A webhook URL was refused: not HTTPS, a non-standard port, or a private or internal address. | |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests. Wait for the number of seconds in Retry-After. |
| 500 | Something failed on our side. Retry with backoff. |
Rate limits
Each API key may make 120 requests a minute per key, counted across the REST API and the MCP server. The jobs, candidates and webhook subscription routes also have a lower limit of their own. Bulk invitations use a separate, lower limit instead. Over the limit, a request answers 429:
HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: …
X-RateLimit-Remaining: 0
X-RateLimit-Reset: …
{ "error": "Rate limit exceeded. …", "code": "RATE_LIMIT_EXCEEDED", "retryAfter": 23 }Wait the number of seconds in Retry-After before trying again. Limits are counted per server, so treat the figure as a ceiling, and spread bulk work out instead of sending it in a burst. Large imports belong in one importApplicants call or one bulk invitation call, not many single ones; see the API reference.
Retrying safely
- Retry
429and500with backoff. Don’t retry4xxerrors other than429without changing the request. importApplicantsis safe to repeat: a candidate already on the job is counted underexisting, not added twice.- Bulk invitations skip anyone already invited to the job, so a repeated call does not double-invite or double-charge.
requestSchedulequeues a new scheduling job on every call. Don’t retry it blindly after a timeout; checklistSchedulesfirst.