Error handling

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.

{
  "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.
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.

Code	Message
ALREADY_EXISTS_RESOURCE	Já existe um para a referência informada.
INVALID_RESOURCE	é inválido.
ENTITY_IN_ANALYSIS	Entidade está em análise, aguarde a aprovação. Referência: #.
ENTITY_INVALID_CURRENCY	Moeda da transação diferente da informada na entidade. Utilize a moeda #.
ENTITY_INVALID_ADDRESS	Entidade não possui endereço válido. Referência: #.
BANK_ACCOUNT_IN_ANALYSIS	Conta bancária está em análise, aguarde a aprovação. Referência: #.
BANK_ACCOUNT_DAILY_TRANS_LIMIT_REACHED	Limite diário de transações atingido.
BANK_ACCOUNT_DAILY_AMOUNT_LIMIT_REACHED	Limite diário de valor de transações atingido.
BANK_ACCOUNT_OVERNIGHT_TRANS_LIMIT_REACHED	Limite noturno de transações atingido.
BANK_ACCOUNT_OVERNIGHT_AMOUNT_LIMIT_REACHED	Limite noturno de valor de transações atingido.
BANK_ACCOUNT_MIN_SINGLE_TRANS_AMOUNT_REACHED	Limite mínimo do valor da transação não foi atingido.
BANK_ACCOUNT_MAX_SINGLE_TRANS_AMOUNT_REACHED	Limite máximo do valor da transação atingido.
BANK_ACCOUNT_MAX_COUNTERPARTY_TRANS_REACHED	Limite diário de transações para uma contrapartida atingido.
BANK_ACCOUNT_MAX_COUNTERPARTY_AMOUNT_REACHED	Limite diário de valor de transações para uma contrapartida atingido.
PIX_KEY_CANCELED	Chave Pix está cancelada. Referência: #.
PIX_KEY_CONFIRMED	Chave Pix já foi confirmada. Referência: #.
PIX_KEY_ALREADY_EXISTS	Já existe uma chave Pix criada ou confirmada. Referência: #.
PIX_KEY_INVALID_KEY	—
PIX_KEY_REQUIRED	A chave deve ser informada quando o tipo é ‘random_key’.
PIX_KEY_INVALID_TYPE	O tipo deve ser: ‘tax_number’, ‘email’, ‘phone’ ou ‘random_key’.
PIX_KEY_CONFIRMATION_TYPE_INVALID	Confirmação com código deve ser executada somente para chaves Pix do tipo: ‘email’ ou ‘phone’.
PIX_KEY_PENDING	Chave Pix não foi confirmada. Referência: #.
COLLECTING_DOCUMENT_NOT_SETTLED	Documento de recebimento não está liquidado. Referência: #.
COLLECTING_DOCUMENT_WITHOUT_BALANCE	Valor da devolução #, maior que o saldo # do documento de recebimento.
PAYMENT_BRCODE_ALREADY_USED	Brcode #, já possui um documento vinculado #.
PAYMENT_AMOUNT_ERROR	Valor de pagamento # deve ser igual ao valor do brcode #, valor #.
PAYMENT_ACCOUNT_WITHOUT_BALANCE	Saldo insuficiente para executar o pagamento. Saldo atual #.
QUERY_LIMIT_REACHED	Limite de consultas atingido. Tente novamente em 1 minuto.
KEY_NOT_FOUND	Chave Pix não foi encontrada. Referência: .
BRCODE_NOT_FOUND	Brcode não foi encontrado. Referência: .
KEY_NOT_FOUND_MULTI_ATTEMPTS	Chave Pix não foi encontrada. Crie a chave e tente novamente em 1 hora. Referência: .

Next steps

Rate limits: what a 429 means and how to back off.
Request identification: the X-Request-Id to quote when you report an error.
Support: channels and what to include in a report.

Getting started

API basics

Webhooks

Error body

HTTP status codes

Error codes

Business rules

Next steps

​Error body

​HTTP status codes

​Error codes

​Business rules

​Next steps

Error body

HTTP status codes

Error codes

Business rules

Next steps