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 de cada SDK; esta página cobre erros no nível do contrato de API.
| Código | Significado | Onde 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. | Endpoints de busca de documentos; API Obter Processo. |
429 Too Many Requests | Você atingiu o rate limit. 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. |
| Causa | Sintoma |
|---|---|
| Chave 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 corretas |
Header APIKEY ausente (somente contrato API) | 401 |
x-api-key inválido (somente Magic Link) | 401 |
Consulte Autenticação > Erros comuns para o checklist completo de troubleshooting.
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:
| Campo | Valor negativo | Onde aparece |
|---|---|---|
process.result | PROCESS_RESULT_FAILED | Web & SDK |
process.authenticationInfo.livenessResult | NO | Web & SDK |
liveness | 2 | API |
unicoId.result | no | API |
data.result.status | not_verified | Magic Link |
Política de retry
| Status | Deve tentar novamente? | Como |
|---|---|---|
5xx | Sim | Backoff exponencial (1s, 2s, 4s, 8s, …). Limite de 5 tentativas. |
429 | Sim | Respeite o header Retry-After se presente; caso contrário, backoff exponencial. |
4xx (outros) | Não | A requisição está incorreta. Corrija a entrada antes de tentar novamente. |
401 | Condicionalmente | Renove o access token uma vez. Se a nova requisição também retornar 401, o problema é estrutural — não tente novamente. |
A 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.
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
- Android SDK > Tratamento de erros
- iOS SDK > Tratamento de erros
- Flutter SDK > Tratamento de erros
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.