Erros e limites

Formato do erro

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

{
  "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).
`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).
`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).
`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, 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.

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.

Comece aqui

Conceitos

Fluxos

Formato do erro

Códigos de erro

Rate limit

Cabeçalhos úteis para suporte

​Formato do erro

​Códigos de erro

​Rate limit

​Cabeçalhos úteis para suporte

Formato do erro

Códigos de erro

Rate limit

Cabeçalhos úteis para suporte