Estrutura de Erros

Estrutura de exceções da API de crédito.

Todas as respostas de erro da API seguem uma estrutura padronizada. Um mesmo erro pode conter vários problemas ao mesmo tempo, especialmente em erros de validação, em que todas as falhas dos campos enviados são retornadas de uma só vez no campo details.

Estrutura da resposta

CampoTipoDescrição
statusintegerCódigo HTTP do erro. Ex.: 400.
codestringCódigo interno do erro, para categorização. Ex.: CRE-0001.
messagestringMensagem de alto nível que resume o erro. Ex.: Validation failed.
detailsarray de stringLista com as mensagens detalhadas. Pode conter um ou vários erros simultâneos.
trace_idstringIdentificador único da requisição, útil para rastreamento e suporte.

Múltiplos erros na mesma resposta

O campo details agrega todas as validações que falharam na requisição. Em vez de retornar apenas o primeiro erro encontrado, a API devolve a lista completa, permitindo que o cliente corrija todos os pontos de uma vez.

📘

Informação

Ao tratar erros, itere sobre details em vez de considerar apenas a primeira mensagem, cada item corresponde a uma validação distinta.

Exemplo

{
    "status": 400,
    "code": "CRE-0001",
    "message": "Validation failed",
    "details": [
        "value should not be empty",
        "value must be a positive number",
        "value must be a number conforming to the specified constraints",
        "payments_frequency must be one of the following values: monthly, biweekly, weekly, annually, daily",
        "partner_id must be a UUID",
        "installments_quantity must be at most 360",
        "installments_quantity must be at least 1",
        "installments_quantity should not be empty",
        "installments_quantity must be a positive number",
        "installments_quantity must be an integer",
        "installments_quantity must be a number conforming to the specified constraints",
        "indication should not be empty",
        "indication must be one of the following values: pos-fixed, pre-fixed",
        "first_installment_date must be a valid ISO 8601 datetime string with time and timezone, e.g: 2025-01-01T00:00:00.000-03:00",
        "first_installment_date should not be empty",
        "contract_date must be a valid ISO 8601 datetime string with time and timezone, e.g: 2025-01-01T00:00:00.000-03:00",
        "contract_date should not be empty",
        "amortization_table should not be empty",
        "amortization_table must be one of the following values: sac, price",
        "amortization_rule should not be empty",
        "amortization_rule must be one of the following values: 252-business-days, 360-calendar-days, 365-calendar-days, by-period",
        "type_of_calculation must be one of the following values: net_value, gross_value"
    ],
    "trace_id": "919cae86a1d624ff5cdb63d781fa6069"
}

Rastreamento e suporte

Cada resposta de erro traz um trace_id. Ao abrir um chamado de suporte, informe o trace_id correspondente à requisição, ele permite localizar rapidamente o evento nos logs da Grafeno.

Boas práticas de tratamento

  • Verifique o status para o tratamento genérico (ex.: 4xx = erro do cliente, 5xx = erro do servidor).
  • Use o code para categorizar o erro de forma programática.
  • Percorra todos os itens de details e exiba-os ao usuário quando forem erros de validação.
  • Registre o trace_id nos seus logs para facilitar a investigação junto ao suporte.