> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vu-one.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Códigos de Erro e Respostas da Identity Link API

> Referência completa de códigos HTTP e erros da Identity Link API com causas e como resolvê-los.

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`:

```json theme={null}
{
  "type": "ErrorResponse",
  "message": "Descrição legível do erro"
}
```

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

```json theme={null}
{
  "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-de-rota).

## Erros comuns de autenticação

### Token expirado

```json theme={null}
{
  "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](/pt/identity-link/autenticacao).

### Credenciais inválidas

```json theme={null}
{
  "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

```json theme={null}
{
  "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](/pt/identity-link/links).

### Cota de verificações esgotada

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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](/pt/identity-link/kyc).

### Identificador já vinculado

```json theme={null}
{
  "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

```json theme={null}
{
  "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 `/`.

```js theme={null}
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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

<Warning>
  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.
</Warning>

| 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

<CodeGroup>
  ```javascript Node.js theme={null}
  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');
  }
  ```

  ```python Python theme={null}
  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")
  ```
</CodeGroup>

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

<Warning>
  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.
</Warning>


## Related topics

- [Changelog da Identity Link API](/pt/identity-link/changelog.md)
- [Ler a resposta](/pt/vucs/antispoofing-facial/respostas.md)
- [Erros e diagnóstico](/pt/vucs/face-analysis/erros.md)
- [Interpretação de respostas](/pt/vucs/face-analysis/respostas.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.