## Comece pelo código, pela operação e pelo ambiente

As respostas de erro documentadas usam um objeto `detail` com `code` e `message`. Valide também o status HTTP. Não trate um JSON recebido com erro como se fosse uma transação criada.

| Código | Verificação recomendada |
| --- | --- |
| `validation_error` | Campos obrigatórios, tipos, país, locale e limites do contrato |
| `invalid_api_key` | Credencial, revogação e ambiente |
| `tenant_environment_disabled` | Habilitação do Tenant e ambiente |
| `transaction_not_found` | Identificador, Tenant e ambiente corretos |
| `idempotency_conflict` | Mesma chave usada com payload diferente |
| `tenant_ip_not_authorized` | IP de saída autorizado para a operação |
| `api_key_scope_not_allowed` | Permissões da chave para o recurso |

## Separe falha de conexão de recusa do contrato

Uma resposta perdida na criação deixa o resultado incerto. Use a mesma chave de idempotência e o mesmo payload, conforme o [guia de idempotência](/pt-BR/desenvolvedores/kyc/idempotencia). Erros determinísticos de credencial, escopo ou payload precisam de correção; repetição ilimitada só esconde a causa.

Para indisponibilidade temporária, defina timeouts e uma política de repetição limitada no seu cliente. Não invente uma promessa de disponibilidade ou um limite universal de tentativas.

## Compartilhe um diagnóstico útil

Registre horário, ambiente, método, caminho sem segredo, status HTTP e código sanitizado. Quando houver, associe o identificador da transação ao chamado de suporte. Remova a chave, o segredo de webhook, dados pessoais e links de jornada. Compare sua chamada com a [referência](/pt-BR/desenvolvedores/kyc/referencia) e os [exemplos](/pt-BR/desenvolvedores/kyc/exemplos-e-downloads) antes de alterar o fluxo de negócio.