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. Pagamentos: `cardTokenId` inexistente, inativo ou sem vínculo com a organização do merchant; `upsellToken` inexistente, revogado (origem estornada) ou de outra organização (`UPSELL_TOKEN_NOT_FOUND`)
`409 Conflict`	Subcontas: `x-idempotency-key` reutilizada. Pagamentos: requisição com a mesma chave ainda em processamento (`PAYMENT_IN_PROGRESS`); `upsellToken` já consumido ou em uso concorrente (`UPSELL_TOKEN_USED`); pagamento de origem do upsell não está mais pago (`UPSELL_ORIGIN_NOT_PAID`)
`410 Gone`	`upsellToken` expirado: o prazo de 15 minutos após a aprovação do pagamento de origem terminou (`UPSELL_TOKEN_EXPIRED`)
`422 Unprocessable Entity`	Operação recusada pelo provedor (ex.: cartão não provisionado na tokenização), ou `x-idempotency-key` de pagamento reutilizada com payload diferente (`IDEMPOTENCY_PAYLOAD_MISMATCH`)
`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 subcontas, não retry - revise o payload, gere uma nova chave se for uma operação nova.
Em 409 PAYMENT_IN_PROGRESS de pagamentos, a primeira requisição ainda está em processamento: aguarde alguns segundos e reenvie com a mesma chave. O retry pode devolver a transação ou outro 409 enquanto o processamento não terminar. Não há nova cobrança.
Em 422 IDEMPOTENCY_PAYLOAD_MISMATCH, a mesma chave foi reutilizada com um corpo diferente: se for uma operação nova, gere uma chave nova. Detalhes em Autenticação → Idempotência.
Em 404/409/410 de upsellToken, não retry com o mesmo token: ele é de uso único e não é reemitido. Para cobrar o upsell, colete o cartão novamente ou use um cardTokenId do Cofre.