---
title: Códigos de erro
description: Consolidated catalog of HTTP and platform error codes across Web & SDK, API, and Magic Link contracts.
canonical: https://developer.unico.io/pt-BR/dual-api/developers/api-reference/error-codes
locale: pt-BR
generated_by: markdown-export
---

- [/pt-BR/](/pt-BR/)
- [Referência de API](/pt-BR/dual-api/developers/api-reference/)
- Códigos de erro

**Nesta página# Códigos de erro

Esta página é a fonte única de verdade para tratamento de erros. Códigos de erro específicos de SDK estão documentados na página [Tratamento de erros](/pt-BR/dual-api/developers/sdks-and-tools/web/web-sdk/error-handling) de cada SDK; esta página cobre erros no nível do contrato de API.
Códigos de status HTTP
CódigoSignificadoOnde se aplica`200 OK`Requisição realizada com sucesso.Todos os contratos.`201 Created`Recurso criado (raro; a maioria das criações retorna `200`).Contrato API.`400 Bad Request`Payload malformado ou campos obrigatórios ausentes. O corpo identifica os campos problemáticos.Todos os contratos.`401 Unauthorized`Autenticação ausente, expirada ou inválida.Todos os contratos.`403 Forbidden`Autenticação válida, mas o tenant não está habilitado para o recurso solicitado (ex.: chamada de uma capacidade não incluída na sua `APIKEY`).Web & SDK, API.`404 Not Found`O recurso não existe ou não pertence ao tenant autenticado.Todos os contratos.`409 Conflict`O recurso existe, mas não está no estado correto para a operação (ex.: busca de documentos de um processo ainda em andamento).Web & SDK, API.`410 Gone`O recurso existia, mas foi excluído conforme a política de retenção (endpoints de busca de documentos), ou o processo existe mas encerrou em estado de erro — veja [Obter Processo](/pt-BR/dual-api/developers/api-reference/api/get-process).Endpoints de busca de documentos; API Obter Processo.`429 Too Many Requests`Você atingiu o [rate limit](/pt-BR/dual-api/developers/api-reference/rate-limits). Tente novamente com backoff exponencial.Todos os contratos.`5xx`Erro da plataforma. Tente novamente com backoff; se persistir, contate o suporte com o corpo da resposta e o timestamp.Todos os contratos.
Erros de autenticação (`401`)
CausaSintomaChave privada incorreta (assertion assinada com a chave errada)`401`, `Authentication failed (1.2.21)``aud` não corresponde à URL do ambiente`401`Claim `exp` no passado`401`, `Authentication failed`Algoritmo não suportado (use `RS256`)`401`Credenciais de sandbox / produção misturadas`401`, mesmo com credenciais aparentemente corretasHeader `APIKEY` ausente (somente contrato API)`401``x-api-key` inválido (somente Magic Link)`401`
Consulte [Autenticação > Erros comuns](/pt-BR/dual-api/developers/api-reference/authentication#error-codes) para o checklist completo de troubleshooting.
Resultados no nível de capacidade (`200` com resultado negativo)
Um `200 OK` **não** significa que o usuário passou na verificação — significa que a plataforma concluiu o trabalho. A decisão para o usuário está no corpo da resposta, não no status HTTP:
CampoValor negativoOnde aparece`process.result``PROCESS_RESULT_FAILED`Web & SDK`process.authenticationInfo.livenessResult``NO`Web & SDK`liveness``2`API`unicoId.result``no`API`data.response.unico.result``NOT_APPROVED`Magic Link
### Política de retry​

StatusDeve tentar novamente?Como`5xx`SimBackoff exponencial (1s, 2s, 4s, 8s, …). Limite de 5 tentativas.`429`SimRespeite o header `Retry-After` se presente; caso contrário, backoff exponencial.`4xx` (outros)NãoA requisição está incorreta. Corrija a entrada antes de tentar novamente.`401`CondicionalmenteRenove o access token uma vez. Se a nova requisição também retornar `401`, o problema é estrutural — não tente novamente.
IdempotênciaA plataforma IDCloud atualmente não expõe um mecanismo de idempotency-key nos endpoints de criação. Tenha cuidado ao tentar novamente `POST /client/v1/process` ou `POST /processes/v1` — um erro de rede em um `5xx` pode ter efetivamente tido sucesso no lado do servidor, e uma nova tentativa criaria um processo duplicado. Em caso de dúvida, recupere os processos recentes pelo seu ID de correlação interno antes de tentar novamente.
Onde ficam os erros do SDK
Os catálogos de erros do Web SDK, Android SDK, iOS SDK e Flutter SDK estão documentados na página de **Tratamento de erros** dedicada de cada SDK:

[Web SDK > Tratamento de erros](/pt-BR/dual-api/developers/sdks-and-tools/web/web-sdk/error-handling)
[Android SDK > Tratamento de erros](/pt-BR/developers/sdks-and-tools/android/error-handling)
[iOS SDK > Tratamento de erros](/pt-BR/developers/sdks-and-tools/ios/error-handling)
[Flutter SDK > Tratamento de erros](/pt-BR/developers/sdks-and-tools/flutter/error-handling)

Estes cobrem erros do lado do dispositivo (permissão de câmera negada, timeout de captura, rede inacessível no dispositivo) — separados dos erros do lado da API documentados aqui.Última atualização em 8 de out. de 2026**