Erros e respostas

Reconheça os três formatos de erro da API e decida quando repetir uma chamada sem duplicar dinheiro.

Formatos de erro

Validação e regra de negócio

Corpo, query ou parâmetro fora do schema responde 400 em application/problem+json, com o campo em errors[]:

2 "type": "https://api.example.com/problems/validation-error",

3 "title": "Validation Error",

4 "status": 400,

5 "detail": "One or more validation errors occurred.",

6 "instance": "/api/v2/payment/pix/qrcode",

7 "errors": [

8 { "field": "info", "message": "Required", "code": "invalid_type" }

9 ]

10}

Recursos inexistentes, permissões e regras de negócio usam o mesmo formato, sem errors[] e com o motivo em detail: saldo insuficiente e valor abaixo da tarifa respondem 400; carteira sem conta de recebimento ao gerar QR Code responde 422; conta da carteira inativa ou bloqueada responde 403.

Toda resposta JSON, de sucesso ou de erro, traz requestId, o mesmo valor do header x-request-id. Informe-o ao falar com o suporte.

Falha no liquidante

Quando o provedor Pix recusa ou não responde, a API repassa o status dele (ou 502) em application/json:

2 "error": true,

3 "message": "Settlement agent API request failed",

4 "details": {}

Cobrança recusada

Se o liquidante recusar a emissão de um QR Code, a resposta é 422 com o envelope Pix e a transação registrada como failed:

2 "error": "Settlement agent rejected the charge",

3 "success": false,

4 "message": "QR Code generation failed",

5 "data": { "status": "failed", "type": "pix_in", "payload": { "status": "failed" } }

O que fazer em cada status

Status	Significado	Ação
`200`	Consulta concluída	Use `data`
`202`	Pix aceito, ainda não concluído	Aguarde o webhook ou consulte pelo `externalId`
`400`	Entrada inválida ou regra recusada	Corrija; repetir igual falha de novo
`401`	Token ausente ou inválido; na emissão, credencial inválida ou revogada	Confira a credencial ou emita outro token e repita uma vez
`403`	Sem permissão, ou conta da carteira inativa ou bloqueada	Não repita; leia `detail`
`404`	Recurso inexistente ou de outra organização	Confira o identificador
`409`	Conflito de estado ou duplicidade	Consulte o recurso e leia o `type` antes de tentar novamente
`422`	Cobrança recusada pelo liquidante, ou carteira sem conta de recebimento	Gere nova cobrança com outro `externalId`; sem conta, vincule-a antes
`429`	Limite de requisições	Espera progressiva
`5xx`	Falha da API ou do liquidante	Consulte antes de repetir

Hoje, um token expirado pode receber 503 com type terminado em /auth-provider-unavailable, em vez de 401. Emita um token novo para recuperar o acesso. Se a chamada original era um Pix, consulte o estado da operação antes de qualquer reenvio. Se o 503 persistir com token novo, trate como indisponibilidade do serviço de autorização.

Identificar a causa pelo `type`

Erros de domínio podem trazer apenas type, sem code. Use o último segmento do type para distinguir causas com o mesmo status:

Final do `type`	Status	Orientação
`wallet-organization-mismatch`	`403`	Confira o `walletId` e a organização da credencial; a carteira deve pertencer à organização exigida pela operação
`pix-key-in-use`	`409`	A chave está vinculada a uma carteira; se precisar excluí-la, resolva esse vínculo com o responsável antes
`pix-key-already-exists`	`409`	A chave já está cadastrada; consulte as chaves da conta antes de tentar cadastrá-la novamente

Esses casos não indicam falha temporária: repetir a mesma chamada sem resolver a causa não corrige o problema.

Repetição segura

1Timeout ou 5xx num Pix

2 │ consulte pelo externalId, na mesma organização e ambiente

3 ▼

4A transação existe?

5 ├─ 200 → acompanhe o estado; não reenvie

6 └─ 404 ou consulta inconclusiva → mantenha o caso em conciliação

Em operações que movimentam dinheiro, timeout ou 5xx não provam falha. Consulte GET /resource/transactions/external-id/{externalId} com a mesma organização e no mesmo ambiente. Um 404 nessa consulta significa apenas que a transação não foi localizada ali naquele momento; não prova que o liquidante deixou de executar o Pix. Mantenha o pagamento em conciliação e não libere o valor retido nem faça fallback ou reenvio enquanto o resultado for incerto.

Se a transação existir, acompanhe seu estado até a confirmação. Antes de iniciar outro pagamento, obtenha confirmação segura de que o anterior não foi executado; só então use um novo externalId.

O externalId é único em toda a plataforma. Repeti-lo não devolve a transação anterior: a criação falha. Gere-o com um UUID ou com um prefixo exclusivo da sua aplicação.