Erros

Quando uma API da Inovacc recusa ou não consegue concluir uma chamada, ela responde com um status HTTP e um envelope de erro em JSON. Este guia descreve o envelope, os tipos de erro, os códigos que todas as APIs compartilham e o que fazer para cada status: corrigir a requisição, esperar ou tentar novamente.

O envelope

Linguagem

⋮

JSONExemplo

JSON

1{ "error": { "message": "Human-readable explanation", "type": "validation_error", "code": "invalid_body" } }

code é aquilo em que o seu programa deve se basear para ramificar. Os códigos fazem parte do contrato de cada API: dentro de um caminho de versão como /v1, novos códigos podem ser acrescentados, e um código existente mantém o seu significado.
type agrupa os códigos em famílias, úteis para registro em log e tratamento amplo.
message é uma frase fixa em inglês para pessoas. Ela nunca repete um valor da sua requisição (no máximo o nome de um campo recusado) e nunca descreve o que falhou dentro da Inovacc. Não a interprete programaticamente.

Algumas respostas acrescentam um campo ao envelope: um arquivo recusado traz reason (por exemplo executable ou password_protected), e uma conversão de esquema que não se encaixa traz failing_documents, uma contagem. Ignore os campos que você não conhece.

Duas respostas não usam o envelope. Na API de IA, um caminho que não existe responde 404 {"error":"not_found"}. Um WebSocket (uma transmissão de Eventos ou um ouvinte de Dados) recusado antes do upgrade responde com um erro HTTP comum; depois de aberto, ele termina com um código de fechamento.

Tipos

`type`	Significa	Status típico
`validation_error`	A requisição está malformada: um cabeçalho, um campo ou um valor viola as regras.	400
`invalid_request_error`	A requisição está bem formada, mas não pode ser atendida como foi enviada: grande demais, um tipo de arquivo não suportado, uma URL que não pode ser buscada.	400, 413, 415, 422
`authentication_error`	Nenhuma credencial, ou uma que não é válida.	401
`authorization_error`, `permission_error`, `forbidden`	A credencial é válida, mas não pode fazer isto.	403
`not_found_error`, `not_found`	A coisa não existe, ou você não pode saber que ela existe.	404, 410
`conflict_error`, `conflict`	A requisição entra em conflito com o estado atual: uma versão, um modo, um limite de uma coleção.	409
`idempotency_error`	Um id de operação está em uso ou foi usado para outra coisa.	409
`rate_limit_error`, `rate_limited`	Chamadas demais, ou uma cota ou orçamento foi consumido.	429
`api_error`, `service_error`, `service_unavailable`, `internal_error`	Algo do lado da Inovacc, ou uma fonte que ela chamou por você, falhou.	500, 502, 503, 504

As APIs de Dados, de IA e de Eventos usam as famílias acima; a string exata de type pode diferir entre APIs para a mesma família, então trate o code e use o status HTTP como alternativa.

Códigos que toda API compartilha

Status	Código	Significado	O que fazer
401	`missing_credentials`, `invalid_credentials`	Nenhuma chave, ou uma chave que não é válida, expirou ou foi revogada.	Corrija a credencial; não tente de novo sem alterá-la.
403	`forbidden`, `route_forbidden`, `key_disabled`, `capability_not_enabled`	A credencial não pode fazer isto.	Peça a permissão, a rota ou a capacidade.
403	`origin_not_allowed`, `secret_key_in_browser`	Uma chamada de navegador a partir de uma origem não listada, ou uma chave secreta em um navegador.	Liste a origem; use uma chave publicável.
400	`missing_operation_id`, `invalid_operation_id`	IA: um `POST`, `PUT` ou `DELETE` sem um `X-Operation-Id` válido.	Envie de 8 a 128 letras, dígitos, `_` ou `-`.
400	`invalid_body`, `unsupported_field`, `invalid_field`	O corpo ou um parâmetro não é válido para este endpoint.	Corrija a requisição.
404	`*_not_found`	Não existe, ou não é seu.	Confira o id.
409	`operation_in_progress`	O mesmo id de operação ainda está em execução.	Aguarde e tente novamente com o mesmo id.
409	`operation_id_reused`	IA: um id de operação já usado para outro arquivo em uma coleção.	Use um novo id de operação para uma nova operação.
409	`version_conflict`	Dados: o registro mudou desde que você o leu.	Leia de novo e tente novamente.
413	`request_too_large`, `payload_too_large`	O corpo excede o limite de tamanho.	Reduza-o ou envie em partes.
429	`rate_limited`	Requisições demais na janela.	Aguarde `Retry-After` segundos, quando informado.
429	`quota_exceeded`, `concurrency_limited`	IA: uma cota de tokens, de custo ou de simultaneidade se esgotou.	Diminua o ritmo; peça à Inovacc para aumentar a cota.
429	`budget_exhausted`	IA: um orçamento diário foi consumido.	Aguarde até 00:00 UTC (`Retry-After`).
502	`upstream_error`	Uma fonte chamada por você falhou.	Tente novamente com espera crescente.
503	`service_unavailable`	Uma dependência não pôde ser alcançada; nada foi feito nem presumido.	Tente novamente com espera crescente.
504	`timeout_error`	IA: o modelo não começou a responder a tempo.	Tente novamente com espera crescente.

Cada página de produto lista todos os códigos que ele pode devolver, com o que fazer.

Política de novas tentativas

Status	Tentar de novo?	Como
400, 401, 403, 404, 410, 413, 415, 422	Não	A mesma requisição falhará da mesma forma. Corrija-a primeiro.
409 `operation_in_progress`	Sim	Após uma curta espera, com o mesmo id de operação.
409 `version_conflict`	Sim, após reler	Leia o registro, aplique a sua alteração à nova versão, envie o `If-Match` dela.
409, outros códigos	Não	O estado precisa mudar primeiro (crie o banco de dados, aguarde os itens, esvazie a pasta).
429 com `Retry-After`	Sim	Não antes do número de segundos informado.
429 sem `Retry-After`	Mais tarde	Uma cota se esgotou: espere minutos, não segundos, ou aumente-a.
500, 502, 503, 504	Sim	Com espera exponencial e jitter (por exemplo 1, 2, 4, 8 segundos), no máximo algumas vezes.
Erro de rede, sem resposta	Sim	Como para 503.

Repita com segurança. Na API de IA, repita uma chamada que altera algo com o mesmo X-Operation-Id: se a primeira tentativa teve sucesso, você recebe a resposta armazenada em vez de uma segunda execução. Em Dados, repita uma criação com o seu próprio id de registro ou If-None-Match: *, e uma atualização com o mesmo If-Match. Em Eventos, repita uma publicação com a mesma idempotency_key: o event_id original volta com duplicate: true.

Veja também

Autenticação: credenciais e idempotência.
Limites: os tamanhos e taxas por trás de 413 e 429.
Webhooks: como as entregas que falharam são repetidas.