Errors

We try to handle the errors and mistakes beautifully as possible. So we use HTTP codes convention to group the errors:

  • 2xx status codes confirm that your request worked as expected
  • 4xx status codes indicate that the request failed due some invalid information or a validation error
  • 5xx status codes are use when something went wrong at Trio servers and systems.

To better error handling during the integration, we always return the errors in the response body using the following fields:

{
  "error_code": "UNAUTHORIZED_RESOURCE",
  "error_message": "Resource being accessed is unauthorized."
}

HTTP status codes summary

CodeTypeDescription
200SuccessEverything worked as expected.
201SuccessResource created successfully.
204SuccessEverything worked as expected with empty body
400Bad requestRequest returned an error, detail in content.
401UnauthorizedInvalid authentication credentials.
404Not FoundThe requested resource was not found.
408TimeoutThe request timed out and was terminated by the server.
429Too Many RequestsToo many concurrent requests
500Server ErrorSomething went wrong in Trio's infrastructure.

General error handling

CodeStatusMessage
TRIO_SERVICE_UNAVAILABLE503Serviço indisponível
TRIO_SERVICE_REQUEST_TIMED_OUT408Timeout
TRIO_SERVICE_REQUEST_METHOD_FORBIDDEN405Método não permitido
ALREADY_EXISTS_RESOURCE400Já existe um {recurso} para a referência informada.
INVALID_RESOURCE400{recurso} é inválido.
NOT_FOUND_RESOURCE404{resource} não foi encontrado.
INVALID_PARAMETER400Campo {parameter} é inválido.
REQUIRED_PARAMETER400Campo {parameter} é obrigatório.

Authentication error handling

CodeStatusMessage
UNAUTHORIZED_RESOURCE403Recurso não autorizado
TRIO_CLIENT_SECRET_INVALID401Client secret inválida.
TRIO_CLIENT_ID_INVALID404Client id inválida.

Integrations error handling

CodeStatusMessage
INTEGRATION_ERROR500Ocorreu um erro inesperado na integração bancária.
INTEGRATION_TIMEOUT408O tempo de integração bancária foi maior que o esperado.

Business error handling

CodeStatusMessage
ENTITY_IN_ANALYSIS404Entidade está em análise, aguarde a aprovação. Referência: #{id}.
ENTITY_INVALID_CURRENCY400Moeda da transação diferente da informada na entidade. Utilize a moeda #{currency}.
ENTITY_INVALID_ADDRESS404Entidade não possui endereço válido. Referência: #{id}.
BANK_ACCOUNT_IN_ANALYSIS404Conta bancária está em análise, aguarde a aprovação. Referência: #{id}.
BANK_ACCOUNT_DAILY_TRANS_LIMIT_REACHED400Limite diário de transações atingido.
BANK_ACCOUNT_DAILY_AMOUNT_LIMIT_REACHED400Limite diário de valor de transações atingido.
BANK_ACCOUNT_OVERNIGHT_TRANS_LIMIT_REACHED400Limite noturno de transações atingido.
BANK_ACCOUNT_OVERNIGHT_AMOUNT_LIMIT_REACHED400Limite noturo de valor de transações atingido.
BANK_ACCOUNT_MIN_SINGLE_TRANS_AMOUNT_REACHED400Limite mínimo do valor da transação não foi atingido.
BANK_ACCOUNT_MAX_SINGLE_TRANS_AMOUNT_REACHED400Limite máximo do valor da transação atingido.
BANK_ACCOUNT_MAX_COUNTERPARTY_TRANS_REACHED400Limite diário de transações para uma contrapartida atingido.
BANK_ACCOUNT_MAX_COUNTERPARTY_AMOUNT_REACHED400Limite diário de valor de transações para uma contrapartida atingido.
PIX_KEY_CANCELED400Chave pix está cancelada. Referência: #{id}.
PIX_KEY_CONFIRMED400Chave pix já foi confirmada. Referência: #{id}.
PIX_KEY_ALREADY_EXISTS400Já existe uma chave pix criada ou confirmada. Referência: #{key}.
PIX_KEY_INVALID_KEY400--
PIX_KEY_REQUIRED400A chave deve ser informada quando o tipo é 'random_key'.
PIX_KEY_INVALID_TYPE400O tipo deve ser: 'tax_number', 'email', 'phone' ou 'random_key.'
PIX_KEY_CONFIRMATION_TYPE_INVALID400Confirmação com código deve ser executada somente para chaves pix do tipo: 'email' ou 'phone'.
PIX_KEY_PENDING404Chave pix não foi confirmada. Referência: #{id}.
COLLECTING_DOCUMENT_NOT_SETTLED400Documento de recebimento não está liquidado. Referência: #{id}.
COLLECTING_DOCUMENT_WITHOUT_BALANCE400Valor da devolução #{amount}, maior que o saldo #{balance} do documento de recebimento.
PAYMENT_BRCODE_ALREADY_USED400Brcode #{id}, já possui um documento vinculado #{id}.
PAYMENT_AMOUNT_ERROR400Valor de pagamento #{amount} deve ser igual ao valor do brcode #{id}, valor #{amount}.
PAYMENT_ACCOUNT_WITHOUT_BALANCE400Saldo insuficiente para executar o pagamento. Saldo atual #{amount}.
DICT_QUERY_LIMIT_REACHED400Limite de consultas atingido. Tente novamente em 1 minuto.
DICT_KEY_NOT_FOUND404Chave pix não foi encontrada. Referência: {key}.
DICT_BRCODE_NOT_FOUND404Brcode não foi encontrado. Referência: {brcode}.
VIRTUAL_TRANSFER_DIFFERENT_BANK_ACCOUNT400Conta bancária das contas virtuais origem e destino são diferentes. Para transferências virtuais devem ser a mesma.