> For the complete documentation index, see [llms.txt](https://docs.consultarplaca.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.consultarplaca.com.br/api-consultar-placa/padroes-de-resposta.md).

# Padrões de resposta

Todas as rotas da nossa API retornam os dados no formato **JSON**, garantindo uma integração simples e compatível com a maioria das linguagens e frameworks de desenvolvimento.

Além disso, seguimos os padrões de código de status HTTP para indicar o resultado de cada requisição, conforme descrito abaixo:

* **200 - Sucesso:** A requisição foi processada com êxito e os dados foram retornados no corpo da resposta.
* **400 - Erro de Requisição:** Ocorreu um problema com os dados enviados na requisição. Verifique os parâmetros e tente novamente.
* **403 - Permissão Negada:** O usuário não possui permissão para acessar o recurso solicitado. Certifique-se de que suas credenciais e permissões estão corretas.
* **429 - Limite de Requisições Excedido**: O número máximo de requisições permitidas foi atingido. Para garantir a estabilidade do sistema, cada usuário pode realizar até **120 requisições por minuto**. Se receber este erro, tente aumentar o intervalo entre as requisições. Caso sua demanda exija um limite maior, entre em contato para avaliarmos uma possível ampliação.
* **500 - Erro Interno:** Um erro inesperado ocorreu no servidor. Nossa equipe será notificada, mas, caso persista, entre em contato com o suporte.

### Informações complementares 

#### Campo <mark style="color:blue;">status</mark>

Todas as rotas retornaram um campo **status** no corpo da resposta JSON, seguindo o padrão:

* **status = "ok"**: Indica que a requisição foi bem-sucedida (**HTTP 200**).
* **status = "erro"**: Indica que ocorreu uma falha ao processar a requisição. Essa falha pode ser causada por erros do cliente (**HTTP 400, 403**), falta de crédito (**HTTP 402**), limite de requisições (**HTTP 429**) ou erros do servidor (**HTTP 500**).

#### Campo <mark style="color:blue;">tipo\_do\_erro</mark>

Algumas respostas incluirão o campo **tipo\_do\_erro**, que fornece informações um direcionamento simples sobre a natureza do problema. Esse campo facilita a identificação e tratamento do caso, sendo os possíveis erros:

* <mark style="color:blue;">placa\_nao\_encontrada</mark> ou <mark style="color:blue;">chassi\_nao\_encontrado</mark>: Situação ocorre quando não é possível obter informações para a placa ou chassi. Isso pode acontecer porque a placa realmente não existe ou porque o serviço de consulta está temporariamente indisponível. Recomenda-se verificar se a placa foi digitada corretamente e, se estiver correta, tentar novamente mais tarde.
* <mark style="color:blue;">informacao\_nao\_encontrada</mark>: Situação ocorre quando não possuímos a informação para a placa informado.&#x20;
* <mark style="color:blue;">servico\_indisponivel</mark>: Situação em que não foi possível completar a pesquisa. Normalmente em situações que nossos fornecedores encontram-se temporariamente indisponíveis. Recomendamos que repita a requisição novamente em alguns minutos!
* <mark style="color:blue;">credito\_insuficiente</mark>: Situação em que o crédito de sua conta é insuficiente para cobrir o valor da consulta em questão.

### Exemplos de erros

```json
// Placa informada é inválida.
{
    "status": "erro",
    "mensagem": "Placa informada é invalida. Placa deve possuir o formato conforme exemplos: AAA9999 ou AAA9A99!",
    "request": {
        "placa": "AAA022"
    }
}
```

```json
// Placa não encontrada em nossa base. 
// Neste caso é retornado o campo tipo_do_erro com o valor placa_nao_encontrada
{
    "status": "erro",
    "tipo_do_erro": "placa_nao_encontrada",
    "mensagem": "Não foi possível obter informações para a placa informada. Verifique se o valor está correto. Caso esteja, o serviço pode estar temporariamente indisponível. Por favor, tente novamente mais tarde!",
    "request": {
        "placa": "AAA0000"
    }
}

```

```json
// Serviço indisponível. 
// Neste caso é retornado o campo tipo_do_erro com o valor servico_indisponivel
{
    "status": "erro",
    "tipo_do_erro": "servico_indisponivel",
    "mensagem": "Não foi possível completar sua pesquisa. Fornecedores temporariamente indisponíveis. Tente novamente em alguns minutos!",
    "request": {
        "placa": "AAA0000"
    }
}
```