# 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"
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.consultarplaca.com.br/api-consultar-placa/padroes-de-resposta.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.