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, 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 needs Read. Create a key that has it.

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.

invalid-request⁠

Status 400. A query parameter is unknown, repeated or has a value the API does not accept. errors names each one.

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." }]}

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.