Skip to main content
When something goes wrong, the API returns an HTTP error status (4xx/5xx) and a JSON body in the standard format below.

​
Error format

{
  "error": {
    "code": "CONFLICT",
    "message": "E-mail já cadastrado",
    "key": "errors.conflict.duplicate_email",
    "params": { "email": "joao@example.com" },
    "details": { }
  }
}
FieldAlways presentDescription
codeYesStable, machine-readable code (e.g., NOT_FOUND, VALIDATION_ERROR).
messageYesHuman-readable message (fallback in pt-BR).
keyNoi18n key, when the message is translatable.
paramsNoMessage interpolation parameters (e.g., { "email": "..." }).
detailsNoAdditional details (e.g., per-field errors on validation).
Build your logic around the code (and the HTTP status), never around the message text — the text may change or be returned in a different language.

​
HTTP codes

StatusTypical codeMeaningWhat to do
400VALIDATION_ERRORInvalid body/parameters.Fix the payload. Check details.
401UNAUTHORIZEDMissing or invalid API key.Check the x-api-key header.
403FORBIDDENInsufficient permission for the operation.Check the key type/scope.
404NOT_FOUNDResource does not exist (or belongs to another account).Verify the ID.
409CONFLICTState conflict (duplicate, invalid transition).Handle the specific case.
422UNPROCESSABLE_ENTITYRequest understood but cannot be processed.Review the business rule.
429RATE_LIMIT_EXCEEDEDRequest rate limit exceeded.Wait and retry with backoff.
500 / 502 / 503INTERNAL_ERRORServer-side error.Retry with backoff; if it persists, contact support.

​
Validation errors (400)

When one or more fields are invalid, details provides a message per field: 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Erro de validação",
    "details": {
      "items": "É necessário pelo menos 1 item",
      "payments": "Soma dos payments (5000) deve ser igual ao total dos items (4990)"
    }
  }
}

Retry with backoff

On 429 and 5xx, retry with exponential backoff. Combine with Idempotency-Key to avoid duplicating the operation.

Do not retry on 4xx

400/409/422 will not resolve by retrying — fix the request instead.

Log the code and request id

Store the code, status, and response body for diagnostics. Do not log the API key.

Always use idempotency

For write operations, use Idempotency-Key to make retries safe. See Conventions.