Erros - Croma API

Envelope

As respostas bem-sucedidas retornam { "data": … }. As falhas retornam um objeto error e um status HTTP diferente de 2xx. Ramifique pelo código de status, não por um indicador no corpo:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param",
    "message": "String must contain at least 3 character(s)",
    "param": "name",
    "details": { "issues": [{ "path": "name", "message": "String must contain at least 3 character(s)" }] }
  }
}

Campo	Notas
`type`	Categoria geral (veja abaixo).
`code`	Código específico legível por máquina. Ramifique com base neste.
`message`	Legível por humanos; seguro para exibir na interface.
`param`	Campo problemático. Presente em erros de validação.
`details`	Detalhe estruturado opcional (por exemplo, todos os `issues` de validação).

As respostas dos endpoints de dados carregam também um cabeçalho X-Request-Id; inclua-o ao reportar um problema.

Tipos e códigos

Status	`type`	`code`	Significado
`400`	`invalid_request_error`	`invalid_param`	O corpo falhou na validação; veja `param` / `details`.
`400`	`invalid_request_error`	`too_many_results`	A consulta correspondeu a registros demais para retornar. Restrinja-a.
`401`	`authentication_error`	`invalid_api_key`	Chave ausente ou inválida.
`401`	`authentication_error`	`personal_api_key_not_allowed`	Foi usada uma chave pessoal; apenas chaves de organização.
`404`	`not_found_error`	`endpoint_not_found`	Não há um endpoint de API nessa rota. Veja a Referência da API.
`404`	`not_found_error`	`job_not_found`	Não há um trabalho assíncrono com esse id na sua organização.
`405`	`invalid_request_error`	`method_not_allowed`	Método incorreto. Os endpoints de dados são `POST`.
`429`	`rate_limit_error`	`rate_limited`	Cota excedida; veja Limites de taxa.
`5xx`	`upstream_error`	`<source>_upstream`	Uma fonte governamental falhou ou não estava disponível.
`500`	`api_error`	`internal_error`	Erro interno inesperado.

Nem todos os endpoints emitem todos os códigos; a página de referência de cada endpoint lista os seus. Um “sem correspondências” nunca é um 404; é um 200 bem-sucedido: as consultas de registro único retornam found: false, e as buscas retornam uma lista vazia. Um 404 significa que o endpoint ou o id do trabalho em si não existe.

As consultas assíncronas podem falhar como trabalho em vez de como um erro HTTP. Um trabalho com falha carrega o mesmo objeto error no envelope, com code: "job_failed".