Erros

Erros da API pública têm sempre este formato:

{
  "error": {
    "code": "unauthorized",
    "message": "header x-api-key ausente"
  }
}

• code é estável: use-o para decidir o que fazer.
• message é para humanos e não é contrato — pode mudar. Não faça parsing dela.
• Trate primeiro pelo status HTTP. Não presuma que todo 4xx traz error.code.

Status e códigos

Status	error.code	Significado
400	capability_error	Requisição rejeitada pela regra de negócio (ex.: documento malformado).
400	invalid_idempotency_key	Idempotency-Key com menos de 16 ou mais de 128 caracteres.
401	unauthorized	Chave ausente, desconhecida ou token inválido.
403	forbidden	Chave revogada/desabilitada, sem escopo, workspace inativo.
403	quota_not_configured	Chave sem teto diário — não abre dossiê.
403	route_not_in_plan	Rota fora do plano de API do workspace.
404	—	Dossiê inexistente ou de outro workspace. Para current-dossier/lookup: ky_type_not_found (tipo de KY inexistente ou invisível à chave).
409	idempotency_key_in_flight	Outra requisição simultânea com a mesma Idempotency-Key acabou de abrir o dossiê. Repita com a mesma chave.
422	invalid_params	Parâmetro de consulta fora de faixa ou inválido.
422	idempotency_key_conflict	A mesma Idempotency-Key já foi usada com um corpo diferente. Use outra chave.
429	quota_exceeded	Cota diária da chave esgotada.
429	kyc_creation_limit_reached	Freio de criação do workspace.
503	unavailable	Serviço de autenticação temporariamente indisponível.

Ao abrir um dossiê sem perfil de consulta resolvido para o tipo de KY, a API recusa — e nada é gravado — com um destes códigos: no_profile_for_ky_type, profile_not_linked, profile_default_missing. São problemas de configuração do workspace, não do seu código.

O que repetir e o que não repetir

Situação	Repetir?
401, 403	Não. Corrija a chave, o escopo ou o plano.
404, 400, 422	Não sem mudar a requisição.
429	Não até a janela voltar (próximo dia UTC para quota_exceeded).
503, erro de rede, timeout de leitura (GET)	Sim, com espera crescente (1 s, 2 s, 4 s…) e limite de tentativas.
Timeout ou erro de rede no POST /dossiers	Sim, desde que você envie Idempotency-Key: repita com a mesma chave e o mesmo corpo e você recebe o dossiê já aberto, sem cota extra (veja Idempotência). Sem a chave, não repita às cegas: o dossiê pode ter sido aberto, e repetir abre outro e consome outra cota.
409 idempotency_key_in_flight	Sim, com a mesma chave.

dica

Use Idempotency-Key ao abrir dossiês

Sem o header, dois POST iguais são dois dossiês. Com ele, repetir é seguro: veja Idempotência.

Erro no dossiê não é erro HTTP

Um dossiê pode ser aceito (202) e depois falhar no bureau. Nesse caso GET /dossiers/{id} responde 200 com status: "error" e dois campos para tratamento programático:

• error_category: bureau_credencial, bureau_indisponivel, bureau_recusou_consulta, documento_invalido, perfil_nao_resolvido, configuracao_workspace, interno, legado_nao_classificado.
• error_code: token curto e estável (por exemplo http.503). Nunca traz a mensagem do provedor.

Veja o que fazer em cada caso de autenticação em Autenticação e chaves.