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
| Member | Content |
|---|---|
type | the address of the documentation of the code, with the code as anchor |
title | a short English sentence for the code |
status | the HTTP status |
detail | an English sentence for this case. It may change |
instance | the request id, the same value as the header Request-Id |
errorSource | where the error is: headers, path, query or body. Only for rejected input |
code | the identifier you branch on. Exactly one per meaning |
errors | all 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
| Status | When |
|---|---|
400 | the request does not match the schema, an id is not an id, a header is not readable, the version does not exist |
401 | the key is missing or not valid |
403 | the key lacks a scope or a level, or the office lacks the plan |
404 | there is nothing under this id or address |
409 | the request conflicts with the state: a duplicate, an unfinished idempotency key, a rule of the office |
412 | a condition in If-Match does not hold |
422 | an idempotency key was reused with a different body |
429 | too many calls, see Limits |
5xx | an error on our side |
Keep reading
REST API: the first call
The REST API reads and writes the listings, contacts, inquiries, viewings and files of your office. One key, one call, JSON back.
API error codes: what each code means
Every code the REST API returns in the member code of a problem, with its HTTP status and meaning. Generated from the contract.
REST API: limits and throttling
How many calls /v1 accepts per key and per office, which headers show the state and what to do on a 429.