Errors

The problem document every error returns, and what each error code means.

Overview⁠

An error answers with the matching HTTP status and an RFC 9457 problem document. The content type is application/problem+json.

curl -i https://attia.app/api/v1/jobs \  -H "Authorization: Bearer attia_api_not_a_real_key"

{  "type": "https://attia.app/docs/api-errors#invalid-api-key",  "title": "Invalid API key",  "status": 401,  "detail": "The request has no API key, or the key is unknown, revoked or expired.",  "code": "invalid-api-key"}

The problem document⁠

Field	Type	Meaning
`type`	URL	A link to the code's section on this page
`title`	string	A short summary for people
`status`	integer	The HTTP status
`detail`	string	What went wrong, for people. Left out on `internal-error`
`code`	string	The stable name of the error
`errors`	list	With `invalid-request` only: one entry per parameter or body field, with `field` and `message`

Branch on code. It never changes, while title and detail are for people, always in English, and may be reworded.

Codes⁠

invalid-api-key⁠

Status 401. The request has no key, the key is mistyped, or the key is unknown, revoked or expired. The answer carries a WWW-Authenticate: Bearer header. Create a new key and send it in the Authorization header. See Authentication.

browser-not-allowed⁠

Status 403. The request came from a web browser: it carried an Origin header or Sec-Fetch-Mode: cors. The API refuses it before it reads the key. Call the API from a server and keep the key there. See Authentication.

insufficient-scope⁠

Status 403. The key is valid and lacks the permission the operation needs. Reading jobs needs Read, and creating a job needs Write. Subscribing to or deleting a webhook needs Admin, from a key whose member is a workspace admin when the request runs. Reading applications or candidates needs Read candidate data, which the API names candidates:read, and the workspace's Candidate data in the API switch on. Create a key that has the permission, or ask an admin to turn the switch on.

plan-required⁠

Status 403. The API is available on the Business and Enterprise plans, and the key's workspace is on Free or Basic. After a downgrade the workspace keeps its keys, and every call answers this code. Upgrade to Business and the same keys work again.

ip-not-allowed⁠

Status 403. The workspace restricts access by IP address and the call came from an address outside the list. Call from a listed address, or ask a workspace admin to add yours.

workspace-view-only⁠

Status 403. The workspace is view-only, so a write cannot change it. Reads still work, and so does deleting a webhook. A workspace admin chooses a plan in Attia, and the same call works again.

invalid-request⁠

Status 400. A query parameter is unknown, repeated or has a value the API does not accept, or a create's body is not valid. errors names each one. A create also gets this code, naming team_id, for a team it cannot create jobs in.

curl -i "https://attia.app/api/v1/jobs?limit=ten" \  -H "Authorization: Bearer $ATTIA_API_KEY"

{  "type": "https://attia.app/docs/api-errors#invalid-request",  "title": "Invalid request",  "status": 400,  "detail": "One or more parameters are not valid.",  "code": "invalid-request",  "errors": [{ "field": "limit", "message": "Must be an integer from 1 to 100." }]}

idempotency-key-required⁠

Status 400. A create or a webhook delete came without an Idempotency-Key header, or with a value that is not 1 to 255 letters, digits, - or _. Nothing was changed. Send the request again with a key. See Retry a create safely, and for webhooks Retry safely.

idempotency-key-reused⁠

Status 422. The Idempotency-Key belongs to an earlier request of the same kind with another body or another webhook id, or one sent with another API key, or one more than 24 hours old. Nothing was changed. After 90 days the same key counts as new. Send a new key with each new request. See Retry a create safely, and for webhooks Retry safely.

webhook-limit-reached⁠

Status 409. The workspace already has 50 webhooks, or the team the webhook names already has 30. Nothing was created. Delete a webhook you no longer use, in Settings → API or with DELETE /api/v1/webhooks/{id}, and send the create again.

not-found⁠

Status 404. No operation lives at the path you called, or the path names a record your key cannot see. A record that does not exist gets the same answer as one your key cannot see. Paths match exactly, so a trailing slash or a capital letter makes a different path. Check the method, the path and the id against these docs.

rate-limited⁠

Status 429. You sent too many requests. Wait the number of seconds in the Retry-After header and try again. See Rate limits.

api-unavailable⁠

Status 503. The API is switched off or cannot be reached right now. Try again later.

internal-error⁠

Status 500. Something failed on our side, and we have a report of it. Retrying may work. If it keeps failing, contact support.