Erros

Todos os erros da API HTTP e do MCP são application/problem+json, conforme RFC 9457. Isso inclui autenticação, validação, rate limit, saldo insuficiente e dependências indisponíveis. Nunca faça parsing de texto de erro. Use:

status para o fluxo HTTP (retry, login, 404)
code para decisões de produto no cliente, no MCP e em automações
requestId ao abrir um chamado de suporte
errors[].field para destacar campos inválidos em formulários

{
  "type": "https://docs.payable.run/errors/validation_error",
  "title": "Bad Request",
  "status": 400,
  "detail": "One or more request fields are invalid.",
  "instance": "/api/v1/clients",
  "code": "VALIDATION_ERROR",
  "requestId": "d8a19cda-1086-4b92-99c3-4ea116d72111",
  "errors": [{ "field": "email", "message": "email must be an email" }]
}

detail pode ser traduzido ou refinado. code é o identificador estável.

Status HTTP

Status	Quando ocorre
`400`	Parâmetros inválidos
`401`	API key ou token inválido
`402`	Saldo insuficiente (apenas modo live)
`403`	A credencial não possui permissão ou escopo para a operação
`404`	Recurso não encontrado (ou sandbox mismatch)
`409`	Conflito de estado: telefone/CPF duplicado ou Idempotency-Key reutilizada com payload diferente
`429`	Rate limit excedido
`502`	Uma integração upstream falhou ao atender a operação
`503`	Uma integração necessária não está configurada ou está indisponível

Códigos de aplicação

`code`	Quando ocorre
`VALIDATION_ERROR`	Corpo, query ou parâmetro de rota inválido
`BAD_REQUEST`	A requisição é semanticamente inválida
`UNAUTHORIZED`	Token ausente, inválido ou expirado
`INSUFFICIENT_BALANCE`	Carteira sem saldo para a operação live
`FORBIDDEN`	Sem papel ou escopo necessário
`RESOURCE_NOT_FOUND`	Recurso não existe, não pertence à organização ou está em outro modo (live/test)
`CONFLICT`	Estado incompatível, incluindo idempotência conflituosa e unicidade de cliente
`RATE_LIMITED`	Limite por API key ou IP atingido
`MERCADO_PAGO_NOT_CONFIGURED`	PIX automático não está disponível para a organização
`UPSTREAM_ERROR`	Mercado Pago, OpenAI ou storage falhou ao responder
`SERVICE_UNAVAILABLE`	Uma dependência configurada não pode atender à operação
`INTERNAL_ERROR`	Falha inesperada; use `requestId` para suporte

No TypeScript, leia error.code (MCP) ou error.data.code (cliente HTTP da web). Não compare detail.

Retries

Use Idempotency-Key em todas as mutações. Em 429, respeite o header Retry-After. Só faça retry automático em 429, 502 ou 503, mantendo a mesma chave de idempotência para mutações. Não repita 404, 409 ou VALIDATION_ERROR sem corrigir o pedido.