Errors & status codes
The API is strict about HTTP status codes, so your agent can branch on the status alone. Every non-2xx response carries a uniform JSON error envelope.
Last updated 8 Oct 2026
Error shape
{
"error": {
"code": "conflict",
"message": "This candidate has already applied to this role."
}
}
Status codes
| Code | Name | When |
|---|---|---|
| 200 | OK | Successful read or action. |
| 201 | Created | A new resource was created (e.g. an application). |
| 204 | No Content | Success with no body. |
| 400 | Bad Request | Request validation failed (malformed or missing fields). |
| 401 | Unauthorized | Missing, invalid or revoked credential. |
| 403 | Forbidden | Authenticated, but your role can't access this resource. |
| 404 | Not Found | No such resource (or not visible to you). |
| 409 | Conflict | Duplicate — e.g. applying twice to the same role. Applying again inside the role's cooling period answers code `cooling_period` with `detail.applyAgainFrom`. |
| 422 | Unprocessable | A domain rule rejected the request (e.g. a move that needs a reason). |
| 429 | Too Many Requests | Rate limit (reserved). |