Guia

Erros

O formato problem+json e cada código de erro.

Todo erro sai em application/problem+json (RFC 9457). Decida pelo campo code, nunca pelo texto de title ou detail, que podem mudar. O type é um link para a linha do código nesta página.

Exemplo

{
  "type": "https://frotasimples.com/desenvolvedores/erros#validacao",
  "title": "Requisição inválida",
  "status": 422,
  "detail": "Corpo inválido.",
  "code": "validacao",
  "requestId": "req_0000",
  "errors": [
    {
      "campo": "placa",
      "mensagem": "Placa inválida."
    }
  ]
}

Guarde o requestId (também no cabeçalho X-Request-Id): é com ele que o suporte encontra a sua chamada.

Códigos

code	HTTP	Significado	O que fazer
`nao_autenticado`	401	Não autenticado	Envie `Authorization: Bearer <chave>` com uma chave completa e válida.
`chave_revogada`	401	Chave revogada ou expirada	A chave foi revogada ou expirou. Crie outra na tela de Integrações.
`escopo_insuficiente`	403	Escopo insuficiente	Crie uma chave com o escopo que a operação pede (ele aparece na referência).
`plano_sem_api`	403	O plano da Conta não inclui a API	O plano da Conta não inclui a API. Mude de plano para usar a integração.
`modulo_desativado`	403	Módulo desativado na Conta	O módulo foi desligado na Conta (Configurações → Módulos e acesso). Peça ao Proprietário da Conta para religar.
`nao_encontrado`	404	Não encontrado	O recurso não existe nesta Conta. Recurso de outra Conta também responde 404.
`conflito`	409	Conflito	Outra requisição com a mesma Idempotency-Key ainda está rodando, ou a regra de negócio recusou. Espere e repita.
`validacao`	422	Requisição inválida	Corrija os campos listados em `errors[]` antes de repetir.
`idempotencia_divergente`	422	Idempotency-Key reutilizada com outro corpo	A mesma Idempotency-Key foi usada com outro corpo. Gere uma chave nova para a nova operação.
`limite_de_taxa`	429	Limite de requisições excedido	Espere os segundos de `Retry-After` antes de repetir. Distribua as chamadas no tempo.
`interno`	500	Erro interno	Erro do nosso lado. Repita com a mesma Idempotency-Key; se persistir, fale com o suporte citando o `requestId`.
`limite_de_webhooks`	422	Limite de webhooks do plano atingido	O plano não inclui webhooks ou já tem o máximo de endereços. Exclua um webhook (desativado também conta) ou mude de plano.

{ "type": "https://frotasimples.com/desenvolvedores/erros#validacao", "title": "Requisição inválida", "status": 422, "detail": "Corpo inválido.", "code": "validacao", "requestId": "req_0000", "errors": [ { "campo": "placa", "mensagem": "Placa inválida." } ] }

Códigos

code	HTTP	Significado	O que fazer
`nao_autenticado`	401	Não autenticado	Envie `Authorization: Bearer <chave>` com uma chave completa e válida.
`chave_revogada`	401	Chave revogada ou expirada	A chave foi revogada ou expirou. Crie outra na tela de Integrações.
`escopo_insuficiente`	403	Escopo insuficiente	Crie uma chave com o escopo que a operação pede (ele aparece na referência).
`plano_sem_api`	403	O plano da Conta não inclui a API	O plano da Conta não inclui a API. Mude de plano para usar a integração.
`modulo_desativado`	403	Módulo desativado na Conta	O módulo foi desligado na Conta (Configurações → Módulos e acesso). Peça ao Proprietário da Conta para religar.
`nao_encontrado`	404	Não encontrado	O recurso não existe nesta Conta. Recurso de outra Conta também responde 404.
`conflito`	409	Conflito	Outra requisição com a mesma Idempotency-Key ainda está rodando, ou a regra de negócio recusou. Espere e repita.
`validacao`	422	Requisição inválida	Corrija os campos listados em `errors[]` antes de repetir.
`idempotencia_divergente`	422	Idempotency-Key reutilizada com outro corpo	A mesma Idempotency-Key foi usada com outro corpo. Gere uma chave nova para a nova operação.
`limite_de_taxa`	429	Limite de requisições excedido	Espere os segundos de `Retry-After` antes de repetir. Distribua as chamadas no tempo.
`interno`	500	Erro interno	Erro do nosso lado. Repita com a mesma Idempotency-Key; se persistir, fale com o suporte citando o `requestId`.
`limite_de_webhooks`	422	Limite de webhooks do plano atingido	O plano não inclui webhooks ou já tem o máximo de endereços. Exclua um webhook (desativado também conta) ou mude de plano.