> For the complete documentation index, see [llms.txt](https://ajuda.financeiro.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.financeiro.app/api/respostas-e-erros.md).

# Respostas e erros

As respostas da API do [**Falcon Finanças**](https://falcon.financeiro.app) combinam o código HTTP com um envelope JSON padronizado.

## Resposta de sucesso

```json
{
  "success": true,
  "message": "",
  "data": {}
}
```

## Resposta de erro

```json
{
  "success": false,
  "message": "Descrição do erro",
  "data": null
}
```

## Códigos mais comuns

| Código | Significado            | Ação recomendada                                              |
| ------ | ---------------------- | ------------------------------------------------------------- |
| `200`  | Requisição processada  | Utilize os dados retornados.                                  |
| `400`  | Dados inválidos        | Revise parâmetros, corpo e campos obrigatórios.               |
| `401`  | Não autorizado         | Confira as credenciais ou obtenha um novo token.              |
| `404`  | Recurso não encontrado | Confira o identificador e o vínculo com o parceiro.           |
| `500`  | Erro inesperado        | Registre o horário e acione o suporte sem enviar credenciais. |

## Boas práticas

* Não considere somente o campo `success`; confira também o código HTTP.
* Não repita automaticamente requisições que alteram dados sem analisar o resultado anterior.
* Registre um identificador próprio da operação para facilitar a auditoria.
* Em erros temporários, utilize novas tentativas com intervalo progressivo.