Erros - UvviPay Public API

A API segue convenções HTTP padrão. Em caso de erro, você recebe um objeto JSON com os campos statusCode, message e error.

Códigos comuns

Status	Quando acontece
`400 Bad Request`	Falha de validação do payload (ex: campo obrigatório faltando, formato inválido)
`401 Unauthorized`	Headers `client-id`/`client-secret` ausentes ou inválidos
`403 Forbidden`	Produto necessário não habilitado (ex.: `tokenization` em tokenização de cartão)
`404 Not Found`	Subconta não encontrada para o `internalId` informado
`409 Conflict`	`x-idempotency-key` reutilizada com payload diferente, ou estado alterado por outro processo
`422 Unprocessable Entity`	Operação recusada pelo provedor (ex.: cartão não provisionado na tokenização)
`429 Too Many Requests`	Rate limit excedido (5/min em subcontas; 30/min em tokenização)
`500 Internal Server Error`	Erro inesperado no servidor; tentar novamente após alguns segundos

{
  "statusCode": 400,
  "message": [
    "documentNumber deve conter apenas números"
  ],
  "error": "Bad Request"
}

O campo message pode vir como string única ou array de mensagens (no caso de validações do class-validator).

Sempre logue o statusCode e message retornados para debug.
Em 429, aplique backoff exponencial antes de tentar novamente.
Em 5xx, reenvie a mesma x-idempotency-key para evitar duplicação quando o servidor voltar.
Em 409 de idempotência, não retry - revise o payload, gere uma nova chave se for uma operação nova.