AthausDocs

REST API: errors as problem details

Every error from /v1 is an RFC 9457 problem with a real HTTP status, a code to branch on and a request id for support.

Last updated:

Every error from /v1 arrives with its HTTP status and the same JSON, whether validation fails, the key is missing, the address is unknown or the server crashes. The format is problem details (RFC 9457), and the media type is application/problem+json. What each code means is under API error codes. The codes of the app and of the MCP servers have their own page.

{
  "type": "https://docs.athaus.ai/en/api/errors#invalid_query",
  "title": "The query parameters do not match the schema.",
  "status": 400,
  "detail": "limit: Too big: expected number to be <=100",
  "instance": "req_0f3a9c2b7d4e41a8b6c15e9d3a7f2b04",
  "errorSource": "query",
  "code": "invalid_query",
  "errors": [{ "name": "limit", "reason": "Too big: expected number to be <=100", "code": "too_big" }]
}

The members

MemberContent
typethe address of the documentation of the code, with the code as anchor
titlea short English sentence for the code
statusthe HTTP status
detailan English sentence for this case. It may change
instancethe request id, the same value as the header Request-Id
errorSourcewhere the error is: headers, path, query or body. Only for rejected input
codethe identifier you branch on. Exactly one per meaning
errorsall problems of a rejected request, one per field. name is the field or parameter, reason the cause, code a stable code of the cause

Branch on code, never on title or detail. If your client does not know a code, handle it by the HTTP status. New codes are no break. Every code is explained on the page Error codes.

An id that belongs to another office is always 404, never 403. The response does not reveal whether it exists.

A known route with the wrong method answers 405 with method_not_allowed and the header Allow.

The request id

Every response, a good one too, carries the header Request-Id. On an error the same value is in instance. Quote it to support and we find the call.

Status and code

StatusWhen
400the request does not match the schema, an id is not an id, a header is not readable, the version does not exist
401the key is missing or not valid
403the key lacks a scope or a level, or the office lacks the plan
404there is nothing under this id or address
409the request conflicts with the state: a duplicate, an unfinished idempotency key, a rule of the office
412a condition in If-Match does not hold
422an idempotency key was reused with a different body
429too many calls, see Limits
5xxan error on our side

Keep reading

On this page