Errors

Every error response uses the same envelope, with a stable, machine-readable code and the request_id of the call. The HTTP status tells you the class of problem; code tells you exactly what went wrong. The message text follows Accept-Language (pt-BR, en-US, es-ES, fr-FR, defaulting to en-US); code never changes.

{
  "error": {
    "code": "validation_failed",
    "message": "The request has invalid fields.",
    "request_id": "01J8Z3ZQ4H8K2M0T1S9P7YQF5C",
    "details": [
      { "field": "name", "code": "required", "message": "Name is required." }
    ]
  }
}

• code is the only field your integration should branch on. Handle any code you do not recognize by its HTTP status.
• details is always present. It lists the individual problems, typically on 400 and 422, and is an empty array when there is nothing to itemize. Each item carries field (request body field) or parameter (query parameter), code (the rule that was violated), and message. Business rule rejections add reason with the specific cause.
• request_id matches the X-Request-Id response header and the entry in the audit trail (GET /requests/{request_id}). Include this value when you contact support.
• A resource outside the scope of the current credentials returns 404, exactly like a resource that does not exist. The API never confirms the existence of something you cannot see.
• The API fails closed: if the credential state, its permissions, or the rate limiter cannot be verified, the response is 503, never access.
• A validation error executes nothing and does not consume the Idempotency-Key. A 429 response does not count against the rate limit window.

Codes

What to do for each class

If a state-changing request returns 500, 503, or times out, the outcome is uncertain: retry with the same Idempotency-Key. If the first attempt was recorded, the retry returns the same response with Idempotent-Replayed: true and creates nothing new.