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
| Campo | Tipo | Descrição |
|---|---|---|
status | integer | Código HTTP do erro. Ex.: 400. |
code | string | Código interno do erro, para categorização. Ex.: CRE-0001. |
message | string | Mensagem de alto nível que resume o erro. Ex.: Validation failed. |
details | array de string | Lista com as mensagens detalhadas. Pode conter um ou vários erros simultâneos. |
trace_id | string | Identificador ú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
detailsem 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
statuspara o tratamento genérico (ex.:4xx= erro do cliente,5xx= erro do servidor). - Use o
codepara categorizar o erro de forma programática. - Percorra todos os itens de
detailse exiba-os ao usuário quando forem erros de validação. - Registre o
trace_idnos seus logs para facilitar a investigação junto ao suporte.