> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trio.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Error handling

> HTTP status codes, the error body and the error codes returned by the API.

The API groups outcomes by HTTP status code: `2xx` means the request worked as expected, `4xx` means it failed because of invalid information or a validation error, and `5xx` means something went wrong on Trio's side. Every error also returns a JSON body that tells you what went wrong, so you can handle it during the integration.

## Error body

* `error.error_code`: stable `UPPER_SNAKE` identifier of the error, for programs and logs. Branch on this, not on the message.
* `error.error_message`: human-readable explanation of the error.
* `error.errors`: only on `INVALID_PARAMETER` for a request outside the operation's schema, one entry per offending field, with a JSON pointer in `field` and what is wrong with it in `message`.

```json theme={null}
{
  "error": {
    "error_code": "INVALID_PARAMETER",
    "error_message": "Invalid parameters: /amount: Invalid integer. Got: string",
    "errors": [
      {
        "field": "/amount",
        "message": "Invalid integer. Got: string"
      }
    ]
  }
}
```

## HTTP status codes

| Code | Type | Description |
| - | - | - |
| 200 | Success | Everything worked as expected. |
| 201 | Success | Resource created successfully. |
| 204 | Success | Everything worked as expected with empty body. Updates and cancellations answer this way. |
| 400 | Bad request | Malformed request: a body that is not valid JSON, or a missing or outdated `Trio-Version` header. |
| 401 | Unauthorized | Missing or invalid API key credentials. |
| 403 | Forbidden | The API key may not do this, for instance a `Trio-Target-Org-Id` it has no access to, or a write through a read-only access. |
| 404 | Not Found | No resource with this ID. |
| 422 | Unprocessable | Invalid input: a field that fails validation, a missing required field, or a business rule the request breaks. |
| 429 | Too Many Requests | Too many requests, see [Rate limits](https://docs.trio.com.br/v2/developers/rate-limit.md). |
| 500 | Server Error | Something went wrong in Trio's infrastructure. |
| 503 | Service Unavailable | A service needed to answer is unavailable. |

## Error codes

| Code | Status | Description |
| - | - | - |
| MALFORMED\_REQUEST | 400 | The body is not valid JSON. |
| INVALID\_TRIO\_VERSION | 400 | The `Trio-Version` header is missing or is not the current version. |
| INVALID\_CREDENTIALS | 401 | Missing or invalid API key credentials. |
| FORBIDDEN | 403 | The API key may not perform this request on this organization. |
| NOT\_FOUND\_RESOURCE | 404 | No resource with this ID. |
| INVALID\_PARAMETER | 422 | A field is invalid. When the request is outside the operation's schema, `errors` lists every offending field. |
| REQUIRED\_PARAMETER | 422 | A required field is missing. |
| TRIO\_SERVICE\_UNAVAILABLE | 503 | A service needed to answer is unavailable. |

## Business rules

When a request is well formed but breaks a business rule, the API answers `422` and `error_code` carries the code of the rule the request breaks. The rule codes below are the ones documented for V1; V2 answers them with `422` instead of the `400` or `404` shown by V1.

<table><thead><tr><th width="293.9296875">Code</th><th>Message</th></tr></thead><tbody><tr><td>ALREADY\_EXISTS\_RESOURCE</td><td>Já existe um {recurso} para a referência informada.</td></tr><tr><td>INVALID\_RESOURCE</td><td>{recurso} é inválido.</td></tr><tr><td>ENTITY\_IN\_ANALYSIS</td><td>Entidade está em análise, aguarde a aprovação. Referência: #{id}.</td></tr><tr><td>ENTITY\_INVALID\_CURRENCY</td><td>Moeda da transação diferente da informada na entidade. Utilize a moeda #{currency}.</td></tr><tr><td>ENTITY\_INVALID\_ADDRESS</td><td>Entidade não possui endereço válido. Referência: #{id}.</td></tr><tr><td>BANK\_ACCOUNT\_IN\_ANALYSIS</td><td>Conta bancária está em análise, aguarde a aprovação. Referência: #{id}.</td></tr><tr><td>BANK\_ACCOUNT\_DAILY\_TRANS\_LIMIT\_REACHED</td><td>Limite diário de transações atingido.</td></tr><tr><td>BANK\_ACCOUNT\_DAILY\_AMOUNT\_LIMIT\_REACHED</td><td>Limite diário de valor de transações atingido.</td></tr><tr><td>BANK\_ACCOUNT\_OVERNIGHT\_TRANS\_LIMIT\_REACHED</td><td>Limite noturno de transações atingido.</td></tr><tr><td>BANK\_ACCOUNT\_OVERNIGHT\_AMOUNT\_LIMIT\_REACHED</td><td>Limite noturno de valor de transações atingido.</td></tr><tr><td>BANK\_ACCOUNT\_MIN\_SINGLE\_TRANS\_AMOUNT\_REACHED</td><td>Limite mínimo do valor da transação não foi atingido.</td></tr><tr><td>BANK\_ACCOUNT\_MAX\_SINGLE\_TRANS\_AMOUNT\_REACHED</td><td>Limite máximo do valor da transação atingido.</td></tr><tr><td>BANK\_ACCOUNT\_MAX\_COUNTERPARTY\_TRANS\_REACHED</td><td>Limite diário de transações para uma contrapartida atingido.</td></tr><tr><td>BANK\_ACCOUNT\_MAX\_COUNTERPARTY\_AMOUNT\_REACHED</td><td>Limite diário de valor de transações para uma contrapartida atingido.</td></tr><tr><td>PIX\_KEY\_CANCELED</td><td>Chave Pix está cancelada. Referência: #{id}.</td></tr><tr><td>PIX\_KEY\_CONFIRMED</td><td>Chave Pix já foi confirmada. Referência: #{id}.</td></tr><tr><td>PIX\_KEY\_ALREADY\_EXISTS</td><td>Já existe uma chave Pix criada ou confirmada. Referência: #{key}.</td></tr><tr><td>PIX\_KEY\_INVALID\_KEY</td><td>--</td></tr><tr><td>PIX\_KEY\_REQUIRED</td><td>A chave deve ser informada quando o tipo é 'random\_key'.</td></tr><tr><td>PIX\_KEY\_INVALID\_TYPE</td><td>O tipo deve ser: 'tax\_number', 'email', 'phone' ou 'random\_key'.</td></tr><tr><td>PIX\_KEY\_CONFIRMATION\_TYPE\_INVALID</td><td>Confirmação com código deve ser executada somente para chaves Pix do tipo: 'email' ou 'phone'.</td></tr><tr><td>PIX\_KEY\_PENDING</td><td>Chave Pix não foi confirmada. Referência: #{id}.</td></tr><tr><td>COLLECTING\_DOCUMENT\_NOT\_SETTLED</td><td>Documento de recebimento não está liquidado. Referência: #{id}.</td></tr><tr><td>COLLECTING\_DOCUMENT\_WITHOUT\_BALANCE</td><td>Valor da devolução #{amount}, maior que o saldo #{balance} do documento de recebimento.</td></tr><tr><td>PAYMENT\_BRCODE\_ALREADY\_USED</td><td>Brcode #{id}, já possui um documento vinculado #{id}.</td></tr><tr><td>PAYMENT\_AMOUNT\_ERROR</td><td>Valor de pagamento #{amount} deve ser igual ao valor do brcode #{id}, valor #{amount}.</td></tr><tr><td>PAYMENT\_ACCOUNT\_WITHOUT\_BALANCE</td><td>Saldo insuficiente para executar o pagamento. Saldo atual #{amount}.</td></tr><tr><td>QUERY\_LIMIT\_REACHED</td><td>Limite de consultas atingido. Tente novamente em 1 minuto.</td></tr><tr><td>KEY\_NOT\_FOUND</td><td>Chave Pix não foi encontrada. Referência: {key}.</td></tr><tr><td>BRCODE\_NOT\_FOUND</td><td>Brcode não foi encontrado. Referência: {brcode}.</td></tr><tr><td>KEY\_NOT\_FOUND\_MULTI\_ATTEMPTS</td><td>Chave Pix não foi encontrada. Crie a chave e tente novamente em 1 hora. Referência: {key}.</td></tr></tbody></table>

## Next steps

* [Rate limits](https://docs.trio.com.br/v2/developers/rate-limit.md): what a `429` means and how to back off.
* [Request identification](https://docs.trio.com.br/v2/developers/request-identification.md): the `X-Request-Id` to quote when you report an error.
* [Support](https://docs.trio.com.br/v2/getting_started/support.md): channels and what to include in a report.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.