Códigos de Erro e Respostas da Identity Link API

A Identity Link API usa códigos HTTP padrão para indicar o resultado de cada requisição. Quando uma chamada falha, o corpo da resposta contém detalhes que ajudam a identificar e corrigir o problema. Esta página também documenta as mudanças de comportamento introduzidas na versão 2.2.0.

Códigos HTTP

Código	Significado	Causa comum	O que fazer
`200 OK`	Sucesso	Requisição processada corretamente	Nenhuma ação necessária
`201 Created`	Criado	Recurso criado com sucesso (ex: link, webhook)	Use o recurso retornado
`400 Bad Request`	Requisição inválida	Corpo malformado, campo obrigatório ausente ou tipo inválido	Revise o schema do payload
`401 Unauthorized`	Não autorizado	Token ausente, expirado ou inválido	Renove o token em `POST /oauth/token`
`403 Forbidden`	Proibido	Token ausente, `linkId` incorreto no endpoint de status, ou recurso de outra empresa	Verifique credenciais e parâmetros
`404 Not Found`	Não encontrado	Recurso não existe, expirou ou a URL está incorreta	Verifique o ID e o endpoint
`409 Conflict`	Conflito	Operação conflita com o estado atual (ex: link já usado)	Consulte o estado atual do recurso
`410 Gone`	Não disponível	A verificação ultrapassou seu tempo de vida máximo	Crie um novo link e reinicie o fluxo
`422 Unprocessable Entity`	Entidade não processável	Dados semanticamente inválidos ou cota de verificações esgotada	Corrija os valores ou consulte `GET /users/me/stats`
`429 Too Many Requests`	Muitas requisições	Limite de taxa excedido	Implemente backoff exponencial
`500 Internal Server Error`	Erro interno	Falha inesperada no servidor	Tente novamente; se persistir, contate o suporte
`501 Not Implemented`	Não implementado	`grant_type` diferente de `client_credentials`	Use apenas `client_credentials`
`503 Service Unavailable`	Serviço indisponível	Manutenção ou degradação temporária	Consulte `GET /health/status` e tente novamente

Formato das respostas de erro

A maioria dos erros usa o schema ErrorResponse:

{
  "type": "ErrorResponse",
  "message": "Descrição legível do erro"
}

Erros específicos de link (409) usam o schema LinksErrorGetResponse, no qual code é numérico:

{
  "code": 4091,
  "name": "LinkExpired",
  "description": "O link já foi utilizado ou expirou",
  "data": {}
}

O 404 de rota inexistente usa um terceiro formato, sem type: {"message": "...", "resource": "..."}. Veja Erros de rota.

Erros comuns de autenticação

Token expirado

{
  "statusCode": 401,
  "message": "Token expired",
  "error": "Unauthorized"
}

Resolução: chame POST /oauth/token novamente com seu clientId e clientSecret para obter um novo token. O access_token dura 3600 segundos. Veja Autenticação.

Credenciais inválidas

{
  "statusCode": 401,
  "message": "Invalid client credentials",
  "error": "Unauthorized"
}

Resolução: verifique se o Base64 de clientId:clientSecret está correto. Consulte GET /users/me para confirmar suas credenciais ativas.

Erros de criação de link

Tipo de link inválido

{
  "statusCode": 422,
  "message": "Invalid link type. Allowed values: FULL FLOW, ID ONLY",
  "error": "Unprocessable Entity"
}

Resolução: use apenas FULL FLOW ou ID ONLY no campo type. Veja Links de Verificação.

Cota de verificações esgotada

{
  "statusCode": 422,
  "message": "Max verifications reached",
  "error": "Unprocessable Entity"
}

Resolução: consulte GET /users/me/stats para ver o consumo, ou contate o suporte para ampliar o limite.

Erros de verificação

Verificação não encontrada

{
  "statusCode": 404,
  "message": "Verification not found",
  "error": "Not Found"
}

Resolução: verifique se o verificationId está correto e se pertence à sua conta. A partir da versão 2.2.0, este erro também cobre uma verificação expirada ou cujo link não é mais válido.

`linkId` ausente ou incorreto no status

{
  "statusCode": 403,
  "message": "linkId does not match this verification",
  "error": "Forbidden"
}

Resolução: GET /verifications/{id}/status é público e exige o parâmetro linkId desde a versão 2.2.0. Envie sempre o linkId que originou aquela verificação. Veja KYC.

Identificador já vinculado

{
  "statusCode": 409,
  "message": "identifierAlreadyBound",
  "error": "Conflict"
}

Resolução: PATCH /verifications/identify recebeu um e-mail diferente para um link cujo externalUserId foi definido pela API na criação. Um identificador fornecido pela API não pode ser sobrescrito: crie um novo link com o identificador correto.

Erros de rota

Rota não implementada

{
  "message": "given resource is not implemented",
  "resource": "/webhook-endpoints"
}

Esse 404 se refere à rota, não a um registro inexistente: nenhuma rota da API coincidiu com a requisição. Ele não segue o schema ErrorResponse: não tem type, e o campo resource devolve o path exatamente como chegou ao servidor. Resolução: verifique se a URL inclui o prefixo /api/v1. É a causa mais comum: ao unir o path com uma URL base, muitos clientes HTTP descartam /api/v1 quando o path começa com /.

new URL('/webhook-endpoints', 'https://api.identity.vu-one.com/api/v1')
// → https://api.identity.vu-one.com/webhook-endpoints
new URL('webhook-endpoints', 'https://api.identity.vu-one.com/api/v1')
// → https://api.identity.vu-one.com/api/webhook-endpoints

Termine a URL base com / e escreva o path sem / inicial, ou use a URL completa. Confira também o path e o método HTTP na documentação. Não é preciso habilitar nada na sua conta: todos os endpoints documentados estão disponíveis na mesma URL base.

Erros de geolocalização

Campo derivado enviado pelo cliente

{
  "statusCode": 400,
  "message": "tier, policy, ipDistanceKm and serverIp are not accepted properties",
  "error": "Bad Request"
}

Resolução: os quatro campos são derivados no servidor. Remova-os do payload de PATCH /verifications.

Origem de dispositivo sem coordenadas

{
  "statusCode": 400,
  "message": "device source requires deviceLatitude and deviceLongitude",
  "error": "Bad Request"
}

Resolução: ao declarar source como gps, wifi ou cell, envie obrigatoriamente deviceLatitude e deviceLongitude. Nada a jusante consegue usar apenas metade do par.

`capturedAt` fora da janela

{
  "statusCode": 400,
  "message": "capturedAt is more than 24 hours from server time",
  "error": "Bad Request"
}

Resolução: sincronize o relógio do dispositivo e envie o horário real da amostra.

Mudanças de comportamento na versão 2.2.0

Em versões anteriores à 2.2.0, PATCH /verifications e PATCH /verifications/error respondiam 200 mesmo quando nenhuma ação era executada. Atualize sua integração antes de migrar.

Endpoint	Situação	Antes	A partir de 2.2.0
`PATCH /verifications`	Verificação inexistente ou expirada	200 sem alterações	404
`PATCH /verifications`	Status não permite a operação	200 sem alterações	409
`PATCH /verifications/error`	Verificação inexistente ou expirada	200 sem alterações	404
`PATCH /verifications/error`	Status não permite a operação	200 sem alterações	409
`GET /verifications/{id}/status`	`linkId` ausente ou incorreto	Parâmetro não existia	403
`GET /billing/{idSubscription}`	Assinatura de outra empresa	Não verificado	403

Estratégia de retry

async function fetchWithRetry(url, options, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const res = await fetch(url, options);
    if (res.ok) return res;
    if (res.status === 429 || res.status >= 500) {
      const delay = Math.pow(2, i) * 1000; // backoff exponencial
      await new Promise(r => setTimeout(r, delay));
      continue;
    }
    throw new Error(`HTTP ${res.status}: ${res.statusText}`);
  }
  throw new Error('Max retries exceeded');
}

import time
import requests

def fetch_with_retry(url, options, retries=3):
    for i in range(retries):
        response = requests.request(url=url, **options)
        if response.ok:
            return response
        if response.status_code == 429 or response.status_code >= 500:
            delay = 2 ** i  # backoff exponencial
            time.sleep(delay)
            continue
        response.raise_for_status()
    raise Exception("Max retries exceeded")

Para erros 429, leia o cabeçalho Retry-After se presente e aguarde o tempo indicado antes de tentar novamente.

Não faça retry em erros 400, 401, 403, 404, 409 ou 422. Esses erros indicam problemas na requisição que não serão resolvidos com novas tentativas.

Primeiros Passos

Conceitos-Chave

Referência

Códigos de Erro e Respostas da Identity Link API

Códigos HTTP

Formato das respostas de erro

Erros comuns de autenticação

Token expirado

Credenciais inválidas

Erros de criação de link

Tipo de link inválido

Cota de verificações esgotada

Erros de verificação

Verificação não encontrada

`linkId` ausente ou incorreto no status

Identificador já vinculado

Erros de rota

Rota não implementada

Erros de geolocalização

Campo derivado enviado pelo cliente

Origem de dispositivo sem coordenadas

`capturedAt` fora da janela

Mudanças de comportamento na versão 2.2.0

Estratégia de retry

​Códigos HTTP

​Formato das respostas de erro

​Erros comuns de autenticação

​Token expirado

​Credenciais inválidas

​Erros de criação de link

​Tipo de link inválido

​Cota de verificações esgotada

​Erros de verificação

​Verificação não encontrada

​linkId ausente ou incorreto no status

​Identificador já vinculado

​Erros de rota

​Rota não implementada

​Erros de geolocalização

​Campo derivado enviado pelo cliente

​Origem de dispositivo sem coordenadas

​capturedAt fora da janela

​Mudanças de comportamento na versão 2.2.0

​Estratégia de retry

Códigos HTTP

Formato das respostas de erro

Erros comuns de autenticação

Token expirado

Credenciais inválidas

Erros de criação de link

Tipo de link inválido

Cota de verificações esgotada

Erros de verificação

Verificação não encontrada

`linkId` ausente ou incorreto no status

Identificador já vinculado

Erros de rota

Rota não implementada

Erros de geolocalização

Campo derivado enviado pelo cliente

Origem de dispositivo sem coordenadas

`capturedAt` fora da janela

Mudanças de comportamento na versão 2.2.0

Estratégia de retry