> ## Documentation Index > Fetch the complete documentation index at: https://documentacao.credicarro.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Erros e idempotência > Formato de erros, status HTTP, códigos de erro e reenvio seguro ## 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`: ```json theme={null} { "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`: ```json theme={null} { "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 | > [!NOTE] > > 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](https://documentacao.credicarro.com.br/pages/guides/document-upload.md). | ### 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. | > [!TIP] > > 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. **1. 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. **2. Envie a chave no cabeçalho** Inclua `Idempotency-Key: ` na requisição. **3. 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. ```bash theme={null} 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. > [!WARNING] > > 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](https://documentacao.credicarro.com.br/pages/customer/reference.md#criar-x-atualizar). ### 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 > [!WARNING] > > 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.