Trate falhas de forma previsível

Formato de erro

Validações podem incluir details sanitizado. Use error.code e o status HTTP, não o texto da mensagem, para lógica de negócio.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Dados inválidos",
    "details": {}
  }
}

Códigos HTTP

400 indica payload, cursor ou idempotência inválidos; 401 indica API key inválida; 403 cobre permissão, entitlement ou plano; 404 oculta recursos fora do tenant; 409 é conflito; 429 é rate limit; 500 é falha interna controlada.

Códigos comuns

INVALID_API_KEY, INSUFFICIENT_PERMISSION, PRO_REQUIRED, GATEWAY_NOT_FOUND, VALIDATION_ERROR, INVALID_IDEMPOTENCY_KEY, PLAN_LIMIT_REACHED, INVALID_MERCHANT, MERCHANT_NOT_FOUND, RATE_LIMITED e INTERNAL_ERROR fazem parte dos fluxos atuais.

Rate limit

Por padrão, cada API key permite 1.000 chamadas por hora. Leia RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset. Os aliases X-RateLimit-* também são enviados e uma resposta bloqueada inclui Retry-After.

Paginação

Listagens aceitam limit entre 1 e 100. Quando hasMore for true, envie nextCursor na chamada seguinte. Não reutilize cursores entre gateways ou filtros diferentes.

Retentativas seguras

Use backoff exponencial com jitter em 429 e falhas transitórias. Na criação de Pix, preserve a mesma Idempotency-Key durante a tentativa lógica; uma nova compra usa outra chave.