Erros

Todos os erros usam o formato RFC 9457 (application/problem+json). Baseie sua lógica no campo code, que é estável. As mensagens em detail podem mudar.

json

{
  "type": "https://datacar.digitalmart.com.br/docs/erros#validation_failed",
  "title": "Parâmetros inválidos",
  "status": 422,
  "code": "validation_failed",
  "detail": "1 parâmetro(s) inválido(s).",
  "instance": "/v1/vehicles/005340-6/2015-3",
  "request_id": "req_4b1f0c6e2d8a4f7e9c3b5a1d0e2f4a6b",
  "errors": [{ "path": "view", "message": "Invalid option: expected one of \"full\"|\"flat\"" }]
}

Status	code	Significado
400	`bad_request`	Parâmetros incoerentes (ex.: busca sem q/brand/model, cursor inválido).
400	`invalid_fipe_code`	Código FIPE malformado ou com dígito verificador errado.
400	`invalid_year`	Ano inválido. Use 2015, 2015-3 (ano-combustível FIPE) ou 0km.
400	`invalid_plate`	Placa fora dos formatos ABC1234 e ABC1D23.
400	`invalid_vin`	Chassi com tamanho errado ou com as letras I, O ou Q.
401	`unauthorized`	Chave ausente, inválida, expirada ou revogada.
403	`forbidden`	A chave não tem o escopo necessário.
403	`ip_not_allowed`	O IP de origem não está na allowlist da chave.
403	`subscription_inactive`	Teste expirado, assinatura cancelada/pendente ou conta suspensa. Veja o painel.
404	`vehicle_not_found`	A FIPE não lista o código/ano/combustível (não consome cota).
404	`plate_not_found`	O provedor não encontrou a placa (não consome cota).
404	`not_found`	Rota ou recurso inexistente.
413	`payload_too_large`	Corpo acima de 256 KB.
422	`validation_failed`	Campos inválidos; veja a lista em errors[].
429	`rate_limited`	Limite por minuto excedido; respeite Retry-After.
429	`quota_exceeded`	Cota mensal da organização esgotada.
500	`internal_error`	Erro inesperado; informe o request_id ao suporte.
501	`plate_lookup_disabled`	A consulta por placa não está habilitada neste ambiente.
503	`source_unavailable`	As fontes não responderam; retente após Retry-After.

Quando retentar

429 e 5xx: retente com backoff exponencial e jitter, respeitando Retry-After.
202 não é erro: o veículo está sendo consultado nas fontes; repita após Retry-After.
4xx (exceto 429): corrija a requisição; repetir não vai ajudar.