Guias
Start typing to search…

Guia de erros

Introdução

Durante o processo de integração e/ou consumo de uma API, é normal recebermos mensagens de erro. Os erros recebidos servem para indicar a existência de inconsistências na operação realizada, ou mesmo a ocorrência de problemas internos no serviço solicitado.

A partir disso, esse guia irá apresentar os principais erros que podem ser recebidos durante o consumo da API do Credere.

Erros de validação

Dentre os vários erros que podem ser retornados nas chamadas da API do Credere, um importante conjunto são os erros de validação.

Esse tipo de erro pode ser retornado em vários endpoints, embora os principais sejam os de criação de cliente e atualização de cliente.

Através dos erros de validação, obtemos informações importantes que permitem identificar qual informação foi enviada de forma inconsistente, e motivou o lançamento do erro.

As principais informações contidas no erro são:

  • Mensagem (message): Mensagem explicativa do erro;
  • Status: Código HTTP do status da resposta;
  • Detalhes (details): Detalhe sobre do erro, composto por: nome do campo, tipo do erro, valores aceitáveis e outras possíveis informações adicionais;

Abaixo temos alguns exemplos de ocorrências:

Campo de texto muito longo

Ocorre quando um campo de texto (string) é enviado com valor maior que o permitido.

Exemplo

Ao tentar atualizar o cliente (customer) com nome (name) maior que 255 caracteres, obtemos:

{
	"error": {
		"class": "ModelValidationError",
		"message": "Nome é muito longo (máximo: 255 caracteres)",
		"status": 422,
		"details": {
			"name": [ // ------------------------- Nome do campo
				{
					"error": "too_long", // ------ Tipo do erro
					"count": 255 // -------------- Tamanho máximo permitido no campo
				}
			]
		}
	}
}

Valor numérico muito grande

Ocorre quando um campo de numérico (number) é enviado com valor maior que o permitido.

Exemplo

Ao tentar atualizar o cliente (customer) com renda mensal (job_referentece.income_cents) maior que 2147483647, obtemos:

{
	"error": {
		"class": "ModelValidationError",
		"message": "Emprego não é válido. Emprego: Renda mensal deve ser menor ou igual a 2147483647",
		"status": 422,
		"details": {
			"job_reference": {
				"income_cents": [ // ---------------------------- Nome do campo
					{
						"error": "less_than_or_equal_to", // ---- Tipo do erro
						"count": 2147483647, // ----------------- Valor máximo permitido
						"value": 2147483648 // ------------------ Valor enviado
					}
				],
				"valid": false,
				"object": {
					"id": 15,
					"customer_id": 14,
					"name": "Nome da empresa",
					"cnpj": "00.000.000/0000-00",
					"joined_at": "2010-01-01",
					"department": null,
					"professional_ocupation_id": 3,
					"detail": null,
					"function": null,
					"income_cents": 2147483648,
					"income_as_string": null,
					"created_at": "2022-12-13T11:03:57.775-03:00",
					"updated_at": "2022-12-19T14:47:22.681-03:00",
					"legacy_id": null,
					"legacy_ocupation": null,
					"another_income_cents": null,
					"another_income_as_string": null,
					"another_income_origin": null,
					"company_activity_id": null,
					"first_job": null,
					"profession_id": 2,
					"previous_work": "Nome da empresa",
					"previous_work_start_at": "2000-01-01",
					"previous_work_end_at": "2000-01-01",
					"another_income_type_id": 2
				}
			}
		}
	}
}

Valor numérico muito pequeno

Ocorre quando um campo de numérico (number) é enviado com valor menor que o permitido.

Exemplo 1

Ao tentar atualizar o cliente (customer) com renda extra (job_referentece.another_income_cents) menor que 0, obtemos:

{
	"error": {
		"class": "ModelValidationError",
		"message": "Emprego não é válido. Emprego: Renda extra deve ser maior ou igual a 0",
		"status": 422,
		"details": {
			"job_reference": {
				"another_income_cents": [ // ----------------------- Nome do campo
					{
						"error": "greater_than_or_equal_to", // ---- Tipo do erro
						"count": 0, // ----------------------------- Valor mínimo permitido
						"value": -10 // ---------------------------- Valor enviado
					}
				],
				"valid": false,
				"object": {
					"id": 15,
					"customer_id": 14,
					"name": "Nome da empresa",
					"cnpj": "00.000.000/0000-00",
					"joined_at": "2010-01-01",
					"department": null,
					"professional_ocupation_id": 3,
					"detail": null,
					"function": null,
					"income_cents": 100000,
					"income_as_string": null,
					"created_at": "2022-12-13T11:03:57.775-03:00",
					"updated_at": "2022-12-19T14:47:22.681-03:00",
					"legacy_id": null,
					"legacy_ocupation": null,
					"another_income_cents": -10,
					"another_income_as_string": null,
					"another_income_origin": null,
					"company_activity_id": null,
					"first_job": null,
					"profession_id": 2,
					"previous_work": "Nome da empresa",
					"previous_work_start_at": "2000-01-01",
					"previous_work_end_at": "2000-01-01",
					"another_income_type_id": 2
				}
			}
		}
	}
}

Exemplo 2

Ao tentar atualizar o cliente (customer) com renda mensal (job_referentece.income_cents) igual a 0, obtemos:

{
	"error": {
		"class": "ModelValidationError",
		"message": "Emprego não é válido. Emprego: Renda mensal deve ser maior que 0",
		"status": 422,
		"details": {
			"job_reference": {
				"income_cents": [ // ------------------- Nome do campo
					{
						"error": "greater_than", // ---- Tipo do erro
						"value": 0.0, // --------------- Valor enviado
						"count": 0 // ------------------ Valor enviado deve ser superior a esse valor
					}
				],
				"valid": false,
				"object": {
					"id": 15,
					"customer_id": 14,
					"name": "Nome da empresa",
					"cnpj": "00.000.000/0000-00",
					"joined_at": "2010-01-01",
					"department": null,
					"professional_ocupation_id": 3,
					"detail": null,
					"function": null,
					"income_cents": 0,
					"income_as_string": null,
					"created_at": "2022-12-13T11:03:57.775-03:00",
					"updated_at": "2022-12-19T14:47:22.681-03:00",
					"legacy_id": null,
					"legacy_ocupation": null,
					"another_income_cents": null,
					"another_income_as_string": null,
					"another_income_origin": null,
					"company_activity_id": null,
					"first_job": null,
					"profession_id": 2,
					"previous_work": "Nome da empresa",
					"previous_work_start_at": "2000-01-01",
					"previous_work_end_at": "2000-01-01",
					"another_income_type_id": 2
				}
			}
		}
	}
}

Valor não permitido

Ocorre quando um campo é enviado com valor não permitido.

Exemplo 1

Ao tentar atualizar o cliente (customer) com Tipo do documento (document_type) igual a "random_type_123", obtemos:

{
	"error": {
		"class": "ModelValidationError",
		"message": "Tipo de documento random_type_123 is not a valid document_type",
		"status": 422,
		"details": {
			"document_type": [ // ------------------- Nome do campo
				{
					"error": "inclusion", // -------- Tipo do erro
					"valid_values": [ // ------------ Valor(es) permitido(s)
						"RG"
					],
					"value": "random_type_123" // --- Valor enviado
				}
			]
		}
	}
}

Exemplo 2

Ao tentar atualizar o cliente (customer) com Tipo de endereço (address.address_type_id) diferente de "principal", obtemos:

{
	"error": {
		"class": "ModelValidationError",
		"message": "Endereço: Tipo de endereço Anterior não está incluído na lista",
		"status": 422,
		"details": {
			"address": {
				"address_type": [ // ---------------- Nome do campo
					{
						"error": "inclusion", // ---- Tipo do erro
						"valid_values": [ // -------- Valor(es) permitido(s)
							"Principal"
						],
						"value": "Anterior" // ------ Valor enviado
					}
				],
				"valid": false,
				"object": {
					"id": 46,
					"addressable_id": 14,
					"addressable_type": "Customer",
					"street": "Avenida Amintas Barros",
					"number": "3700, Sala 409 Bloco A",
					"reference": null,
					"complement": "Edifício Corporate Tower Center-Trade",
					"city": "Natal",
					"state_id": 20,
					"lat": null,
					"long": null,
					"created_at": "2022-12-13T11:03:57.761-03:00",
					"updated_at": "2022-12-14T18:59:34.053-03:00",
					"set_time_month": 1,
					"set_time_year": 0,
					"build_type_old": null,
					"neighborhood": "Lagoa Nova",
					"zip_code": "59075-810",
					"legacy_state": null,
					"build_type_id": 3,
					"rent_value_cents": 100000,
					"rent_value_as_string": null,
					"address_type_id": 2,
					"main": false
				}
			}
		}
	}
}

Valor inválido

Ocorre quando um campo é enviado com valor inválido.

Exemplo

Ao tentar atualizar o cliente (customer) com e-mail (emails.address) igual a "cliente", obtemos:

{
	"error": {
		"class": "ModelValidationError",
		"message": "E-mail: Endereço de e-mail não é válido. E-mails não é válido",
		"status": 422,
		"details": {
			"emails": [
				{
					"address": [ // -------------------- Nome do campo
						{
							"error": "invalid", // ----- Tipo do erro
							"value": "cliente" // ------ Valor enviado
						}
					],
					"valid": false,
					"object": {
						"id": 12,
						"address": "cliente",
						"contactable_id": 14,
						"contactable_type": "Customer",
						"created_at": "2022-12-13T11:03:57.893-03:00",
						"updated_at": "2022-12-13T11:03:57.893-03:00"
					}
				}
			]
		}
	}
}

Campo obrigatório não preenchido

Ocorre quando um campo obrigatório não é preenchido/enviado.

Exemplo

Em alguns bancos, ao tentar criar o cliente (customer) com a cidade do endereço (address.city) em branco, obtemos:

{
	"error": {
		"class": "ModelValidationError",
		"message": "Endereço não é válido. Endereço: Cidade não pode ficar em branco",
		"status": 422,
		"details": {
			"address": {
				"city": [ // -------------------- Nome do campo
					{
						"error": "blank" // ----- Tipo do erro
					}
				],
				"valid": false,
				"object": {
					"id": 46,
					"addressable_id": 14,
					"addressable_type": "Customer",
					"street": "Avenida Amintas Barros",
					"number": "3700, Sala 409 Bloco A",
					"reference": null,
					"complement": "Edifício Corporate Tower Center-Trade",
					"city": null,
					"state_id": 20,
					"lat": null,
					"long": null,
					"created_at": "2022-12-13T11:03:57.761-03:00",
					"updated_at": "2022-12-14T18:59:34.053-03:00",
					"set_time_month": 1,
					"set_time_year": 0,
					"build_type_old": null,
					"neighborhood": "Lagoa Nova",
					"zip_code": "59075-810",
					"legacy_state": null,
					"build_type_id": 3,
					"rent_value_cents": 100000,
					"rent_value_as_string": null,
					"address_type_id": 1,
					"main": false
				}
			}
		}
	}
}

Quantidade de objetos menor que o exigido

Ocorre quando um campo possui menos objetos do que é exigido.

Exemplo

Em alguns bancos, ao tentar criar o cliente (customer) com apenas 1 telefone (phones), obtemos:

{
	"error": {
		"class": "ModelValidationError",
		"message": "Telefones mínimo: 2 telefones para contato",
		"status": 422,
		"details": {
			"phones": [ // ----------------------- Nome do campo
				{
					"valid": true,
					"object": {
						"id": 156,
						"phonable_id": 14,
						"phonable_type": "Customer",
						"code": 84,
						"number": 999999999,
						"created_at": "2022-12-13T11:03:57.867-03:00",
						"updated_at": "2022-12-13T11:03:57.867-03:00",
						"phone_type_id": 1,
						"phone_type_legacy": null,
						"talk_to": null,
						"branch": null,
						"old_number": null,
						"phone_confirmation_id": null
					}
				},
				{
					"error": "too_short", // ----- Tipo do erro
					"count": 2 // ---------------- Quantidade mínima exigida
				}
			]
		}
	}
}

Campo de data/hora posterior ao permitido

Ocorre quando um campo de data/hora é ou está à frente do valor permitido.

Exemplo 1

Ao tentar atualizar o cliente (customer) com data de emissão do documento (rg_date) além da data atual, obtemos:

{
	"error": {
		"class": "ModelValidationError",
		"message": "Data de emissão deve ser em ou antes de 03/11/2023",
		"status": 422,
		"details": {
			"rg_date": [ // ------------------------- Nome do campo
				{
					"error": "on_or_before", // ------ Tipo do erro
					"restriction": "03/11/2023" // --- Data máxima permitida
				}
			]
		}
	}
}

Exemplo 2

Ao tentar atualizar o cliente (customer) com data de início no emprego anterior (job_referentece.previous_work_start_at) é ou está além da data de término no emprego anterior (job_referentece.previous_work_end_at), obtemos:

{
	"error": {
		"class": "ModelValidationError",
		"message": "Emprego não é válido. Emprego anterior: Data de admissão deve ser antes de 01/01/2000",
		"status": 422,
		"details": {
			"job_reference": {
				"previous_work_start_at": [ // ----- Nome do campo
					{
						"error": "before", // ---------- Tipo do erro
						"restriction": "01/01/2000" // - 1 dia além da data máxima permitida
					}
				],
				"valid": false,
				"object": {
					"id": 15,
					"customer_id": 14,
					"name": "Nome da empresa",
					"cnpj": "00.000.000/0000-00",
					"joined_at": "2010-01-01",
					"department": null,
					"professional_ocupation_id": 3,
					"detail": null,
					"function": null,
					"income_cents": 0,
					"income_as_string": null,
					"created_at": "2022-12-13T11:03:57.775-03:00",
					"updated_at": "2022-12-19T14:47:22.681-03:00",
					"legacy_id": null,
					"legacy_ocupation": null,
					"another_income_cents": null,
					"another_income_as_string": null,
					"another_income_origin": null,
					"company_activity_id": null,
					"first_job": null,
					"profession_id": 2,
					"previous_work": "Nome da empresa",
					"previous_work_start_at": "2000-01-02",
					"previous_work_end_at": "2000-01-01",
					"another_income_type_id": 2
				}
			}
		}
	}
}

Updated 7 months ago