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

# Erros e limites

> Os códigos estáveis, o que fazer com cada um, e como respeitar o rate limit.

## Formato do erro

Uma chamada recusada sempre devolve `data: null` e um ou mais itens em `errors`:

```json theme={null}
{
  "data": null,
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "field": "customerDocument",
      "message": "customerDocument: Documento do cliente é obrigatório"
    }
  ]
}
```

Use sempre `errors[0].code` na sua lógica de tratamento — é o único campo com valores estáveis.
`message` existe para gente ler durante o desenvolvimento, nunca para decisão de código: seu
conteúdo pode mudar sem aviso.

## Códigos de erro

| Código | HTTP | Significado | O que fazer |
| - | - | - | - |
| `VALIDATION_ERROR` | 400 | Um campo da requisição é inválido ou está faltando. `errors[0].field` nomeia o campo. | Corrija o campo indicado e tente de novo. Não repita sem alterar o corpo. |
| `INVALID_API_KEY` | 401 | A chave de API enviada a `POST /v1/auth/token` é inexistente, revogada ou expirou. | Confirme a chave com a Koolisys; se foi revogada, peça uma nova. |
| `INVALID_TOKEN` | 401 | O token é inválido, expirou, ou a chave que o emitiu foi revogada. | Peça um novo token com `POST /v1/auth/token` (veja [Autenticação](https://docs-koolisys.eixoassistencia.com.br/autenticacao.md)). |
| `INSUFFICIENT_SCOPE` | 403 | O token não tem o escopo exigido por este endpoint. `errors[0].details.requiredScope` nomeia o escopo que falta. | Peça à Koolisys uma chave com o escopo necessário — não adianta tentar de novo com o mesmo token. |
| `NOT_FOUND` | 404 | O recurso não existe, ou pertence a outra contratante (as duas situações são indistinguíveis de propósito). | Confirme o identificador. Não existe uma variação deste erro que revele "existe, mas não é seu". |
| `CUSTOMER_ALREADY_EXISTS` | 409 | O documento (ou `externalCode`) já está cadastrado num cliente da sua contratante. `errors[0].details.customerId` aponta o registro existente. | Não é um erro fatal numa carga: siga usando o cliente apontado em `details.customerId`. |
| `VEHICLE_ALREADY_EXISTS` | 409 | A placa (ou `externalCode`) já pertence a um veículo ativo. `errors[0].details.vehicleId` aponta o registro quando ele é da sua contratante; o mesmo erro vem sem detalhes quando a placa está ativa em outra contratante. | Com `details.vehicleId`, siga usando esse veículo. Sem detalhes, confira a placa com o cliente — a API não revela dados de outra contratante. |
| `PLAN_ALREADY_LINKED` | 409 | O plano informado já está vigente nesse cliente/veículo. `errors[0].details.beneficiaryPlanId` aponta o vínculo existente. | Não é um erro fatal numa carga: o vínculo que você queria criar já existe — siga com ele. |
| `IDEMPOTENCY_CONFLICT` | 409 | A `Idempotency-Key` enviada já foi usada com um corpo de requisição diferente. | Gere uma chave nova para a tentativa atual — nunca reaproveite a mesma chave para um corpo diferente (veja [Idempotência](https://docs-koolisys.eixoassistencia.com.br/idempotencia.md)). |
| `NOT_COVERED` | 422 | O cliente/veículo não tem cobertura ativa para o serviço no momento da criação. | Consulte `GET /v1/eligibility` antes de criar para tratar isso como fluxo normal, não como erro inesperado. |
| `PLAN_TARGET_MISMATCH` | 422 | O plano se aplica ao outro alvo: um plano `VEHICLE` não vincula pelo cliente, nem um plano `CUSTOMER` pelo veículo. | Confira o `appliesTo` do plano em `GET /v1/company` e use a rota do alvo certo (veja [Clientes e veículos](https://docs-koolisys.eixoassistencia.com.br/clientes-e-veiculos.md)). |
| `PLAN_NOT_AVAILABLE` | 422 | O plano está inativo no contrato, ou o contrato saiu de vigência — o id existe, mas não aceita vínculos novos. | Escolha um plano vigente de `GET /v1/company`; se ele deveria estar disponível, fale com a Koolisys. |
| `RATE_LIMITED` | 429 | O limite de requisições foi excedido. `errors[0].details.retryAfterSeconds` diz quanto esperar. | Espere o tempo indicado (também disponível no cabeçalho `Retry-After`) antes de repetir. Nunca tente de novo imediatamente. |
| `FEATURE_DISABLED` | 503 | A API pública ainda não está habilitada para a sua contratante. | Fale com a Koolisys. Não é um erro passageiro — repetir não ajuda até a Koolisys habilitar. |

Todo endpoint documenta, na [referência](https://docs-koolisys.eixoassistencia.com.br/referencia/openapi), exatamente quais destes códigos ele
pode devolver — a lista acima é o catálogo completo e fechado; a API pública nunca introduz um
código novo sem documentá-lo aqui primeiro.

## Rate limit

O limite se aplica **por chave**, nunca por endereço de origem — uma integração com vários
servidores compartilha a mesma cota. O padrão é 600 requisições por minuto por contratante
(configurável pela Koolisys por contratante).

Toda resposta de um endpoint de dados carrega os cabeçalhos:

| Cabeçalho | Significado |
| - | - |
| `RateLimit-Limit` | Limite da janela atual. |
| `RateLimit-Remaining` | Quantas requisições ainda cabem na janela atual. |
| `RateLimit-Reset` | Segundos até a janela reiniciar. |
| `Retry-After` | Presente só na resposta `429` — segundos até que valha a pena tentar de novo. |

Monitore `RateLimit-Remaining` e reduza o ritmo antes de bater no limite, em vez de reagir só ao
`429`. Se a checagem de limite falhar internamente (degradação do contador), a resposta segue sem
os cabeçalhos de limite, com `X-RateLimit-Degraded: 1` — a chamada nunca é bloqueada por uma falha
de infraestrutura do lado da Koolisys.

`POST /v1/auth/token` tem seu próprio limite, mais restrito: 10 tentativas por minuto por chave e,
separadamente, 10 por minuto por endereço de origem — ver [Autenticação](https://docs-koolisys.eixoassistencia.com.br/autenticacao.md).

## Cabeçalhos úteis para suporte

Toda resposta traz `X-Request-Id` (ou ecoa o que você enviar no mesmo cabeçalho). Inclua esse valor
ao abrir um chamado com a Koolisys sobre uma chamada específica — ele identifica a requisição nos
registros do lado do servidor sem precisar reenviar dados sensíveis.


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