Errors

Error response format

Every error returns a JSON body together with the matching HTTP status code, so you can branch on both. There are three response shapes to handle.

Most errors — an error object with a human-readable message. This is the shape you’ll hit for 400, 401, 403, resource 404s (e.g. a project that doesn’t exist), and 500. Every message in the table below is returned as this message.

{ "error": { "message": "Project does not exist." } }

Validation errors — a 422 with the standard FastAPI detail array, one entry per field that failed validation:

{
  "detail": [
    { "loc": ["body", "profile_key"], "msg": "field required", "type": "value_error.missing" }
  ]
}

Unknown route — a 404 for a path the API doesn’t define returns a plain detail string:

{ "detail": "Not Found" }

For contrast, successful responses wrap their payload in a data object: { "data": { … } }. So a reliable check is: treat the response as an error whenever error or detail is present, and read the message from error.message (or detail).

Errors you might hit

These are the errors you’re most likely to encounter, with the cause and the fix for each.