Errors

Shape of an error

An error uses the application/problem+json format (RFC 9457), with a stable code:

{
  "type": "https://mabellenote.com/developers/errors#invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "detail": "The request contains invalid fields.",
  "requestId": "req_Qm9uam91ciBNYSBCZWxsZQ",
  "errors": [{ "path": "query.limit", "message": "Must be less than or equal to 100" }]
}

Every response, error or not, carries the X-Request-Id header. Share it with support for any question about a specific call.

Handling an error

• Code against code, never against title or detail, whose wording may change.
• A code never disappears and never changes status within a version. New codes may come with new operations: handle an unknown code based on its HTTP status.
• 429 rate_limited: wait for the number of seconds given by the Retry-After header, then send the request again.
• 409 idempotency_in_progress: a request with the same Idempotency-Key is still running. Send it again a little later, with the same key. The idempotency guide details these cases.
• 503 service_unavailable: the request had no effect. Send it again after the Retry-After delay when present, otherwise after an increasing wait.
• 500 internal_error: send the request again with an increasing wait and a limited number of attempts, then contact support with the requestId.
• Other 4xx errors are not fixed by sending the same request again: fix it first.
• 404 route_not_found means the path does not exist, 404 not_found that the resource is missing or belongs to another account. 405 method_not_allowed lists the accepted methods in the Allow header.

Code catalog

This list comes from the API's OpenAPI description. It is part of the v1 contract.