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

Code	Type	Description
200	Success	Everything worked as expected.
201	Success	Resource created successfully.
204	Success	Everything worked as expected with empty body
400	Bad request	Request returned an error, detail in content.
401	Unauthorized	Invalid authentication credentials.
404	Not Found	The requested resource was not found.
408	Timeout	The request timed out and was terminated by the server.
429	Too Many Requests	Too many concurrent requests
500	Server Error	Something went wrong in Trio's infrastructure.

General error handling

Code	Status	Message
TRIO_SERVICE_UNAVAILABLE	503	Serviço indisponível
TRIO_SERVICE_REQUEST_TIMED_OUT	408	Timeout
TRIO_SERVICE_REQUEST_METHOD_FORBIDDEN	405	Método não permitido
ALREADY_EXISTS_RESOURCE	400	Já existe um {recurso} para a referência informada.
INVALID_RESOURCE	400	{recurso} é inválido.
NOT_FOUND_RESOURCE	404	{resource} não foi encontrado.
INVALID_PARAMETER	400	Campo {parameter} é inválido.
REQUIRED_PARAMETER	400	Campo {parameter} é obrigatório.

Authentication error handling

Code	Status	Message
UNAUTHORIZED_RESOURCE	403	Recurso não autorizado
TRIO_CLIENT_SECRET_INVALID	401	Client secret inválida.
TRIO_CLIENT_ID_INVALID	404	Client id inválida.

Integrations error handling

Code	Status	Message
INTEGRATION_ERROR	500	Ocorreu um erro inesperado na integração bancária.
INTEGRATION_TIMEOUT	408	O tempo de integração bancária foi maior que o esperado.

Business error handling

Code	Status	Message
ENTITY_IN_ANALYSIS	404	Entidade está em análise, aguarde a aprovação. Referência: #{id}.
ENTITY_INVALID_CURRENCY	400	Moeda da transação diferente da informada na entidade. Utilize a moeda #{currency}.
ENTITY_INVALID_ADDRESS	404	Entidade não possui endereço válido. Referência: #{id}.
BANK_ACCOUNT_IN_ANALYSIS	404	Conta bancária está em análise, aguarde a aprovação. Referência: #{id}.
BANK_ACCOUNT_DAILY_TRANS_LIMIT_REACHED	400	Limite diário de transações atingido.
BANK_ACCOUNT_DAILY_AMOUNT_LIMIT_REACHED	400	Limite diário de valor de transações atingido.
BANK_ACCOUNT_OVERNIGHT_TRANS_LIMIT_REACHED	400	Limite noturno de transações atingido.
BANK_ACCOUNT_OVERNIGHT_AMOUNT_LIMIT_REACHED	400	Limite noturo de valor de transações atingido.
BANK_ACCOUNT_MIN_SINGLE_TRANS_AMOUNT_REACHED	400	Limite mínimo do valor da transação não foi atingido.
BANK_ACCOUNT_MAX_SINGLE_TRANS_AMOUNT_REACHED	400	Limite máximo do valor da transação atingido.
BANK_ACCOUNT_MAX_COUNTERPARTY_TRANS_REACHED	400	Limite diário de transações para uma contrapartida atingido.
BANK_ACCOUNT_MAX_COUNTERPARTY_AMOUNT_REACHED	400	Limite diário de valor de transações para uma contrapartida atingido.
PIX_KEY_CANCELED	400	Chave pix está cancelada. Referência: #{id}.
PIX_KEY_CONFIRMED	400	Chave pix já foi confirmada. Referência: #{id}.
PIX_KEY_ALREADY_EXISTS	400	Já existe uma chave pix criada ou confirmada. Referência: #{key}.
PIX_KEY_INVALID_KEY	400	--
PIX_KEY_REQUIRED	400	A chave deve ser informada quando o tipo é 'random_key'.
PIX_KEY_INVALID_TYPE	400	O tipo deve ser: 'tax_number', 'email', 'phone' ou 'random_key.'
PIX_KEY_CONFIRMATION_TYPE_INVALID	400	Confirmação com código deve ser executada somente para chaves pix do tipo: 'email' ou 'phone'.
PIX_KEY_PENDING	404	Chave pix não foi confirmada. Referência: #{id}.
COLLECTING_DOCUMENT_NOT_SETTLED	400	Documento de recebimento não está liquidado. Referência: #{id}.
COLLECTING_DOCUMENT_WITHOUT_BALANCE	400	Valor da devolução #{amount}, maior que o saldo #{balance} do documento de recebimento.
PAYMENT_BRCODE_ALREADY_USED	400	Brcode #{id}, já possui um documento vinculado #{id}.
PAYMENT_AMOUNT_ERROR	400	Valor de pagamento #{amount} deve ser igual ao valor do brcode #{id}, valor #{amount}.
PAYMENT_ACCOUNT_WITHOUT_BALANCE	400	Saldo insuficiente para executar o pagamento. Saldo atual #{amount}.
DICT_QUERY_LIMIT_REACHED	400	Limite de consultas atingido. Tente novamente em 1 minuto.
DICT_KEY_NOT_FOUND	404	Chave pix não foi encontrada. Referência: {key}.
DICT_BRCODE_NOT_FOUND	404	Brcode não foi encontrado. Referência: {brcode}.
DICT_KEY_NOT_FOUND_MULTI_ATTEMPTS	404	Chave pix não foi encontrada. Crie a chave e tente novamente em 1 hora. Referência: {key}.
VIRTUAL_TRANSFER_DIFFERENT_BANK_ACCOUNT	400	Conta bancária das contas virtuais origem e destino são diferentes. Para transferências virtuais devem ser a mesma.