Erros

Toda resposta de erro tem o mesmo formato, em qualquer rota:

{
  "code": "SPLIT_INVALID",
  "message": "A soma do split passa do valor da venda.",
  "details": [
    { "field": "splitRules[1].amountCents", "message": "..." }
  ]
}

Campo	Pra que serve
`code`	O tipo do erro. Estável: é nele que o seu código deve se basear.
`message`	Explicação pra uma pessoa ler. Pode mudar de texto; não compare com ela.
`details`	Só aparece quando dá pra apontar o campo ou cabeçalho com problema.

Como tratar

O código HTTP diz de que lado está o problema, e o que fazer:

Status	O que quer dizer	O que fazer
`400`	O pedido está errado (campo faltando ou inválido)	Corrija e mande de novo. Repetir igual não adianta.
`401`	Chave de API ausente, inválida ou do ambiente errado	Confira a chave e o ambiente.
`403`	A chave não tem permissão pra essa rota	Fale com a SwitchPay.
`404`	O que você pediu não existe ou não é da sua empresa	Confira o id.
`409`	O pedido bate de frente com o estado atual	Veja o `code`: cada um tem um motivo.
`410`	O prazo passou (intenção expirada)	Crie outra.
`422`	O pedido é bem formado, mas uma regra do negócio recusou	Veja o `code` e corrija o dado.
`429`	Muitas chamadas em pouco tempo	Espere o tempo de `Retry-After` e repita.
`5xx`	Falha do nosso lado ou da adquirente	Repita com a mesma `Idempotency-Key`, com intervalo.

Cartão recusado não é erro. Quando o banco recusa o cartão, o confirm responde 201 com a transação em FAILED. Erro HTTP é quando a chamada em si não pôde ser atendida.

Lendo o `details`

Em erro de validação, details traz um item por problema, todos de uma vez:

{
  "code": "VALIDATION_ERROR",
  "message": "...",
  "details": [
    { "field": "amountCents", "message": "..." },
    { "field": "buyer.email", "message": "..." }
  ]
}

field usa o caminho do campo no corpo (buyer.email, splitRules[1].amountCents) ou o nome do cabeçalho (Idempotency-Key). Dá pra usar direto pra marcar o campo errado na sua tela.

Todos os códigos

Pedido e acesso

Código	HTTP	Quando acontece
`VALIDATION_ERROR`	400	Campo ou cabeçalho faltando ou inválido (`details` diz qual)
`UNAUTHORIZED`	401	Chave ausente, inválida, revogada ou do ambiente errado
`FORBIDDEN`	403	Chave sem permissão pra esta rota
`NOT_FOUND`	404	O recurso não existe ou não é seu
`RATE_LIMITED`	429	Muitas chamadas; veja `Retry-After`

Intenção e cobrança

Código	HTTP	Quando acontece
`REFERENCE_ID_IN_USE`	409	`referenceId` já usado por intenção em andamento ou por transação
`INTENT_ALREADY_PROCESSED`	409	Intenção já confirmada, cancelada ou expirada
`INTENT_EXPIRED`	410	A intenção passou dos 5 minutos; crie outra
`PAYMENT_METHOD_NOT_AVAILABLE`	422	Forma de pagamento não habilitada pra sua empresa
`SELLER_NOT_FOUND`	422	Sua empresa ainda não tem conta de vendedor aprovada
`SPLIT_INVALID`	422	Split passa do valor, percentual acima de 100 ou regra sem valor
`SPLIT_RECIPIENT_NOT_FOUND`	422	Documento do split não é de conta aprovada na SwitchPay

Idempotência

Código	HTTP	Quando acontece
`IDEMPOTENCY_KEY_REUSED`	409	Mesma chave com corpo diferente
`IDEMPOTENCY_IN_PROGRESS`	409	A primeira chamada ainda está processando; tente de novo

Cartão e cofre

Código	HTTP	Quando acontece
`TICKET_INVALID`	401	O ticket não é válido pra este cofre ou foi alterado
`TICKET_EXPIRED`	401	O ticket passou dos 5 minutos
`TICKET_USED`	401	O ticket já foi usado
`TOKEN_REQUIRED`	422	Intenção de cartão confirmada sem token
`TOKEN_INVALID`	422	Token inválido, vencido ou de outra intenção

Webhooks e sandbox

Código	HTTP	Quando acontece
`WEBHOOK_URL_INVALID`	422	A URL não é `https` ou aponta pra endereço interno
`SANDBOX_ONLY`	404	A rota só existe no sandbox
`TRANSACTION_NOT_PENDING`	409	No sandbox, só transação `PENDING` pode ser simulada

Falhas do lado de cá

Código	HTTP	Quando acontece
`PROVIDER_ERROR`	502	A adquirente não respondeu ou falhou
`INTERNAL_ERROR`	500	Falha inesperada do nosso lado; repita com a mesma `Idempotency-Key`
`SERVICE_UNAVAILABLE`	503	Serviço fora do ar; nada foi criado; repita depois de `Retry-After`

Boas práticas

Decida o que fazer pelo code, nunca pelo texto de message.
Trate código que você não conhece como erro genérico: a lista pode ganhar itens novos.
Guarde em log o code, o message e o details de todo erro. Facilita muito o suporte.
Em 5xx e em 429, repita com espera crescente entre as tentativas, e sempre com a mesma Idempotency-Key.

Como tratar

Lendo o details

Todos os códigos

Boas práticas

Nesta página

Lendo o `details`