Erros e idempotência

Formato de erro

Os erros retornados pela API seguem o formato abaixo, com campos em português. Um campo inválido retorna o primeiro erro encontrado, com o nome do campo em campo:

{
  "tipo": "Validation.Cpf.Invalid",
  "titulo": "Requisição inválida",
  "status": 400,
  "detalhe": "O CPF informado em 'cpf' é inválido.",
  "campo": "cpf"
}

Um erro de regra de negócio vem sem campo:

{
  "tipo": "Store.Integration.Intermediation",
  "titulo": "Regra de negócio não atendida",
  "status": 422,
  "detalhe": "A loja possui contrato de intermediação e não é elegível para a integração."
}

Campo	Descrição
`tipo`	Código estável do erro (por exemplo, `Store.Integration.NotFound`). Use este campo no seu tratamento.
`titulo`	Categoria do erro.
`status`	Status HTTP.
`detalhe`	Mensagem do erro, para logs e suporte. Pode mudar sem aviso.
`campo`	Campo da requisição relacionado ao erro, quando houver (por exemplo, `endereco.cep`).
`erros`	Lista com `codigo`, `mensagem` e `campo`. Aparece só quando o JSON enviado está malformado ou tem um valor de tipo errado (`codigo` = `Validation.InvalidFormat`).

Status HTTP

Status	Quando ocorre	Repetir?
`400`	Dados inválidos (formato, campo obrigatório ausente).	Não — corrija o corpo
`401`	Token ausente, inválido ou expirado.	Gere um novo token e repita
`403`	Integração inativa ou parceiro não encontrado. Pode ocorrer em qualquer rota autenticada.	Não — fale com o time Credicarro
`404`	Recurso não encontrado ou de outro parceiro (proposta, simulação, cliente, loja ou webhook).	Não
`409`	CPF, e-mail ou celular já cadastrado, `Idempotency-Key` reutilizada com outro conteúdo ou edição simultânea de webhook.	Não — trate pelo `tipo`
`422`	Regra de negócio não atendida (por exemplo, loja com intermediação ou cadastro do cliente incompleto).	Não — trate pelo `tipo`
`500`	Erro inesperado.	Sim, com a mesma `Idempotency-Key`
`502`	Falha ao comunicar com um serviço interno ou externo.	Sim, com espera crescente
`503`	Serviço temporariamente indisponível.	Sim, com espera crescente

Respostas 401 de token ausente ou inválido são devolvidas sem corpo. Falhas inesperadas (500, e alguns 502) podem vir no formato padrão Problem Details, com os campos type, title, status e detail.

Códigos de erro

Os códigos abaixo chegam em tipo.

Validação de campos

Todos retornam 400, com o campo em campo.

Código	Quando ocorre
`Validation.Field.Required`	Campo obrigatório ausente (inclusive headers, como `Idempotency-Key` no envio de documento).
`Validation.Field.TooLong`	Texto maior que o permitido.
`Validation.Field.InvalidOption`	Valor fora das opções aceitas (por exemplo, `tipoOcupacao` ou `participante`).
`Validation.Identifier.Invalid`	Identificador (UUID) inválido ou vazio (por exemplo, `simulacaoId`).
`Validation.Cpf.Invalid`	CPF inválido.
`Validation.Cnpj.Invalid`	`cnpjLoja` inválido.
`Validation.Email.Invalid`	E-mail inválido.
`Validation.Phone.Invalid`	Celular fora do formato `+55 (DD) 99999-9999`.
`Validation.ZipCode.Invalid`	CEP inválido.
`Validation.Uf.Invalid`	UF inválida (`uf` ou `endereco.estado`).
`Validation.BirthDate.Invalid`, `.BelowMinimumAge`, `.AboveMaximumAge`	Data de nascimento futura ou cliente fora da faixa de 18 a 75 anos.
`Validation.Amount.MustBePositive`, `.MustNotBeNegative`	Valor monetário zero ou negativo onde não é permitido (`valorVeiculo`, `valorSolicitado`, `renda`, `valorEntrada`).
`Validation.DownPayment.NotBelowVehicleAmount`	`valorEntrada` igual ou maior que `valorVeiculo`.
`Validation.LicensePlate.Invalid`	Placa inválida.
`Validation.Renavam.Invalid`	Renavam inválido.
`Validation.Chassi.Invalid`	Chassi inválido (17 caracteres, sem I, O e Q).
`Validation.Color.Invalid`	Cor do veículo com números.
`Validation.Bank.InvalidCode`, `.InvalidAgency`, `.InvalidAccountNumber`, `.InvalidCheckDigit`	Dados bancários inválidos.
`Validation.Url.Invalid`	`url` do webhook não é uma URL absoluta http ou https.
`Validation.Paging.InvalidNumber`, `.InvalidSize`	`pagina_inicial` menor que 1 ou `limite` fora de 1 a 100.
`Validation.IdempotencyKey.Invalid`	`Idempotency-Key` vazia ou com mais de 200 caracteres.
`Validation.Document.TypeNotAllowed`	Tipo de documento não aceito para o participante.
`Validation.File.InvalidName`, `.InvalidExtension`, `.InvalidBase64`, `.Empty`, `.TooLarge`	Arquivo do documento inválido. Veja Enviar documentos.

Acesso e autenticação

Código	Status	Quando ocorre
`Integration.Authentication.InvalidCredentials`	`401`	`clientId` ou `clientSecret` inválidos, ou integração inativa.
`Integration.Access.Inactive`	`403`	A integração do parceiro está inativa.
`Integration.Access.OrganizationNotFound`	`403`	O parceiro do token não foi encontrado.

Cliente

Código	Status	Quando ocorre
`Customer.Account.NotFound`	`404`	O CPF não tem cadastro. Cadastre o cliente antes de simular.
`Customer.Account.Incomplete`	`422`	Na proposta, o cadastro está incompleto (endereço, ocupação ou renda).
`Cpf.CpfAlreadyAdded`, `Email.EmailAlreadyAdded`, `Phone.PhoneAlreadyAdded`	`409`	Na criação, o CPF, o e-mail ou o celular já estão cadastrados.
`Account.IdempotencyKeyReused`	`409`	`Idempotency-Key` reutilizada com outro conteúdo.

Loja e simulação

Código	Status	Quando ocorre
`Store.Integration.NotFound`	`404`	O `cnpjLoja` não existe ou não está vinculado ao parceiro.
`Store.Integration.Intermediation`	`422`	A loja tem contrato de intermediação e não pode ser usada na integração.
`Simulation.Access.NotFound`	`404`	A simulação não existe ou é de outro parceiro.
`Simulation.Access.NotFromStore`	`422`	Na proposta, a simulação não foi feita para uma loja.
`Simulation.Terms.Unavailable`	`422`	Não há prazos disponíveis para o veículo.
`Proposal.DownPaymentInvalid`	`422`	Nenhum prazo aceita a entrada informada.
`Proposal.RequestAmountInvalid`	`422`	Valor solicitado inválido: entrada que deixa menos de 10% do veículo para financiar, ou valor fora da faixa refinanciável.
`Simulation.Refinancing.AmountOutOfRange`	`422`	O `valorSolicitado` não cabe na faixa de nenhum prazo.
`Simulation.Refinancing.UfUnavailable`	`422`	Não foi possível identificar a UF do veículo nem do endereço do cliente.
`Proposal.SimulationIdempotencyConflict`	`409`	`Idempotency-Key` reutilizada com outro conteúdo na simulação.

Proposta

Código	Status	Quando ocorre
`Proposal.Access.NotFound`	`404`	A proposta não existe ou é de outro parceiro.
`Proposal.Access.NotIntegrationV2`	`422`	A proposta não pode ser consultada ou alterada por esta rota.
`Proposal.Customer.ProfileNotFound`	`404`	O cliente da proposta não foi encontrado.
`Proposal.Customer.ProfileAmbiguous`	`502`	Na listagem, não foi possível identificar o cliente de uma proposta.
`Proposal.IdempotencyKeyReused`	`409`	`Idempotency-Key` reutilizada com outro conteúdo na criação da proposta.
`Proposal.SimulationAlreadyActivated`	`422`	O `simulacaoId` já foi usado em outra proposta. Cada opção de simulação gera uma única proposta.
`Proposal.SimulationAlreadyExpired`	`422`	A simulação expirou. Faça uma nova simulação.
`Proposal.BuyerAgeNotAllowed`	`422`	O cliente não tem entre 18 e 75 anos na criação da proposta.
`Proposal.InvalidStatus`	`422`	Dados do veículo enviados fora da etapa `DADOS_VEICULO`.
`Proposal.ProposalIsNotInDepositAccountStatus`	`422`	Conta de recebimento enviada fora da etapa `CONTA_RECEBIMENTO`.
`Proposal.DepositAccount.OnlyRefinancing`	`422`	Conta de recebimento enviada para uma proposta de financiamento.
`Proposal.DepositAccount.HolderNotBuyer`	`422`	O `cpfTitular` da conta não é o CPF do cliente da proposta.

Envio de documento

Código	Status	Quando ocorre
`Document.InvalidProposalStage`	`422`	A etapa ativa não permite o envio de documentos.
`Document.NotPendingCorrection`	`422`	Na correção, o tipo enviado não está recusado.
`Document.InvalidContent`	`422`	O conteúdo real do arquivo não corresponde à extensão informada.
`Document.InvalidProposalModality`	`422`	A modalidade da proposta não permite envio de documentos pela integração.
`Idempotency.KeyConflict`	`409`	A `Idempotency-Key` já foi usada com outro conteúdo.
`Document.UploadFailed`	`502`	Não foi possível armazenar o documento. Tente de novo com a mesma `Idempotency-Key`.

Webhooks

Código	Status	Quando ocorre
`Webhook.Registration.NotFound`	`404`	O webhook não existe ou é de outro parceiro.
`Organization.Webhook.InvalidEndpoint`	`422`	URL inválida: precisa ser HTTPS pública, sem localhost, IP privado, usuário/senha ou `#fragmento`.
`Organization.Webhook.ActivationIntegrationInactive`	`422`	Não é possível ativar o webhook com a integração inativa.
`Organization.Webhook.ConcurrencyConflict`	`409`	O webhook foi alterado ao mesmo tempo por outra requisição. Tente de novo.
`Organization.Webhook.CredentialProtectionUnavailable`	`503`	Não foi possível proteger a credencial agora. Tente de novo.

Trate os códigos que fazem sentido para o seu fluxo e tenha um tratamento genérico por status para os demais. Novos códigos podem ser adicionados.

Reenvio seguro com Idempotency-Key

As rotas listadas abaixo aceitam o cabeçalho Idempotency-Key. Ele permite repetir uma requisição com segurança após um timeout ou erro de rede, sem criar registros duplicados.

Gere uma chave única por operação

Antes de chamar a API, gere um identificador único para aquela operação. A chave deve ter de 1 a 200 caracteres — recomendamos um UUID.

Envie a chave no cabeçalho

Inclua Idempotency-Key: <sua-chave> na requisição.

Reenvie com a mesma chave se precisar tentar novamente

Se a chamada falhar por timeout ou erro de rede, repita a requisição com a mesma chave e o mesmo corpo. A API devolve o resultado original, sem repetir a operação.

curl -X POST https://api.staging.credicarro.com.br/integration/v2/proposal \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c9a2e-3b7d-4e2a-9c51-0d8f3a7b2e10" \
  -d '{ "cpf": "12345678909", "simulacaoId": "bea8d060-f93d-48eb-b6c4-45f64483cdd9" }'

Chave reutilizada com outro conteúdo

Retorna 409 Conflict. Uma mesma Idempotency-Key fica atrelada ao conteúdo da primeira requisição.

No cadastro de cliente, a chave muda o comportamento: com Idempotency-Key, POST /v1/customer/unified só cria. Para atualizar um cliente, envie sem a chave. Veja Cliente.

Estratégia de retentativa

Repita só respostas 500, 502 e 503, falhas de rede e timeouts
Espere um tempo crescente entre as tentativas (por exemplo, 0,5 s, 1 s, 2 s e 4 s)
Limite o número de tentativas (por exemplo, 4) e registre a falha depois disso

Gere a Idempotency-Key fora da rotina de retentativa. Todas as tentativas precisam usar a mesma chave.

Rotas que aceitam Idempotency-Key

Rota	Header
`POST /v1/customer`, `/v1/customer/unified`, `/v1/customer/address`, `/v1/customer/professional`	Opcional
`POST /v1/proposal/simulation/financing`, `/v1/proposal/simulation/refinancing`	Opcional
`POST /v2/proposal/simulation/financing`, `/v2/proposal/simulation/refinancing`	Opcional
`POST /v1/proposal`, `POST /v2/proposal`	Opcional
`POST /v2/proposal/{propostaId}/document`	Obrigatório

As rotas de webhook, de dados do veículo e de conta de recebimento não usam o header.

Integração

Guias

Ajuda

Erros e idempotência

Formato de erro

Status HTTP

Códigos de erro

Validação de campos

Acesso e autenticação

Cliente

Loja e simulação

Proposta

Envio de documento

Webhooks

Reenvio seguro com Idempotency-Key

Chave reutilizada com outro conteúdo

Estratégia de retentativa

Rotas que aceitam Idempotency-Key

​ Formato de erro

​ Status HTTP

​ Códigos de erro

​Validação de campos

​Acesso e autenticação

​Cliente

​Loja e simulação

​Proposta

​Envio de documento

​Webhooks

​ Reenvio seguro com Idempotency-Key

Chave reutilizada com outro conteúdo

​Estratégia de retentativa

​Rotas que aceitam Idempotency-Key

Formato de erro

Status HTTP

Códigos de erro

Validação de campos

Acesso e autenticação

Cliente

Loja e simulação

Proposta

Envio de documento

Webhooks

Reenvio seguro com Idempotency-Key

Estratégia de retentativa

Rotas que aceitam Idempotency-Key