Erros

A API trabalha com três modelos principais de erro. A estrutura da resposta indica a natureza do problema: regra de negócio, validação de dados ou falha de integração.

⚠️

Importante

Para garantir o recebimento das mensagens no formato correto, as requisições devem incluir o cabeçalho version: cutting-edge.

Modelos de Erro

1. Erro de Regra de Negócio

Este é o formato padrão para erros operacionais, como registros não encontrados (404) ou violações de regras de negócio (400, 403, 409, 422).

Característica: message é uma string simples.

{
  "status": "error",
  "statusCode": 404,
  "errorCode": "BOLETO_NOT_FOUND",
  "message": "Boleto not found with authentication code uuid-invalido."
}

2. Erro de Validação de Dados

Retornado quando os dados enviados na requisição estão incorretos ou incompletos (400).

Característica: Possui o campo data, que é um objeto contendo os detalhes do erro. Este objeto pode ser aninhado (para validar sub-objetos) e conter múltiplos campos com erro simultaneamente.

Exemplo Complexo (Aninhado e Múltiplo):

{
  "status": "error",
  "statusCode": 400,
  "errorCode": "INVALID_INPUT",
  "message": "A requisição apresenta dados inválidos. Apresente este código no suporte: c901ba38-2f81-44c4-81a7-ad8f55d4b971.",
  "data": {
    "payer": {
      "address": {
        "state": "The state must be a valid Brazilian state abbreviation."
      }
    },
    "sender": {
      "name": "Use only letters, numbers, spaces, dots, commas, ampersand and hyphens."
    }
  }
}

📘

Nota

Para evitar a ocorrência de erros 400, siga as instruções de preenchimento dos campos disponíveis na documentação correspondente a cada endpoint.

3. Erro do Provedor

Ocorre quando há uma rejeição ou falha proveniente de um parceiro externo ou validação de integração.

Característica: message é sempre um array de strings e a resposta inclui um correlationId fora do objeto data.

{
  "status": "error",
  "statusCode": 400,
  "errorCode": "INVALID_BILL_BAR_CODE",
  "message": [
    "Invalid bill bar code"
  ],
  "correlationId": "0e341584-4448-4aa3-bf8d-4184dfe85ff3"
}

Catálogo de Códigos de Erro (errorCode)

Abaixo estão listados os códigos de erro mais comuns que podem ser retornados em qualquer um dos modelos acima.

Autenticação e Segurança

Transações e Pagamentos

Contas e Usuários

Boletos e Pagamentos

Validação Geral