Tratamento de erros

Sempre que houve algum problema na requisição (seja um parâmetro inválido, problema na autenticação ou um erro interno inesperado), a API retornará um erro. Ele deverá possuir alguns campos que ajudam a identificar a causa do problema.

Código (code)

Representa o tipo do erro. Na maioria dos casos, os erros possuem sub-erros que descrevem mais detalhes sobre sua causa. São estes os valores possíveis:

  • UNAUTHORIZED: Não autorizado. Representa um problema de autenticação com a API.

  • FORBIDDEN: Ação não permitida.

  • INTERNAL_SERVER_ERROR: Erro interno da aplicação.

  • BAD_REQUEST_BODY: Requisição mal construída. Normalmente acontece quando o body não corresponde ao formato esperado.

  • NOT_FOUND: Recurso não encontrado.

  • TIMEOUT: Nosso servidor não pode responder a requisição em menos de 30 segundos.

Mensagem (message)

Este campo contém uma mensagem legível sobre a causa do problema.

Sub-erros

É uma lista de detalhes mais específicos sobre a causa do(s) problema(s). Cada sub-erro também possui um código e mensagem específicos. São estes os valores de código de sub-erro possíveis:

  • INVALID_BODY: Corpo da requisição inválido;

  • PERMISSION_DENIED: Não é possível realizar esta Ação, verifique suas permissões;

  • PARAM_NOT_FOUND: Não encontramos um recurso com este <paramName>;

  • INVALID_TOKEN: Token inválido;

  • INVALID_FIELD_VALUE: '<fieldName>' inválido;

  • INTEGRATION_NOT_ENABLED: A integração '<name>' não está habilitada. Entre em contato conosco;

  • INVALID_SPLIT_PERCENTAGE: Valor inválido para split;

  • INVALID_PHONE: Telefone inválido;

  • INVALID_PROVIDER: Provedor de recarga inválido;

  • PAST_DUE_DATE: A data de expiração <dueDate> não se refere a um valor futuro;

  • CANNOT_EXECUTE_WHILE_PROCESSING: Estamos processando a criação deste recurso. Tente novamente em alguns segundos;

  • ACCOUNT_CANT_HAVE_BALANCE: A Conta não pode possuir saldo para realizar esta operação;

  • ALREADY_EXISTS: Esta informação já foi vinculada a esta Conta anteriormente;

  • INVALID_CPF: Cpf inválido;

  • INVALID_EMAIL: E-mail inválido;

  • FIELDS_WITH_INVALID_VALUE: O campo 'fields' só deve armazenar valores chave-valor do tipo string;

  • MISSING_KYC: Falta de documentação ou a documentação ainda está pendente de aprovação;

  • BATCH_LIMIT_EXCEEDED: O limite máximo de Ações em um Lote é 20;

  • INVALID_ACTION_TYPE: <type> não é um tipo válido de Ação;

  • ASSET_NOT_FOUND: Ativo não encontrado;

  • TO_NOT_FOUND: Destinatário não encontrado;

  • FROM_NOT_FOUND: Remetente não encontrado;

  • INVALID_AMOUNT: Valor inválido;

  • UNDERFUNDED: Saldo insuficiente.

  • EXTERNAL_SERVICE: Ocorreu um erro inesperado em um serviço parceiro nosso. Nesse caso, repassaremos a mensagem recebida.

Segue um exemplo do corpo de uma requisição com um erro 404:

{
"status": 404,
"error": {
"name": "NOT_FOUND",
"message": "Recurso não encontrado.",
"code": "NOT_FOUND",
"subErrors": [
{
"code": "TO_NOT_FOUND",
"msg": "Destinatário não encontrado.",
"index": 0
}
]
}
}