Erros

Um envelope. type para a família, code estável, request_id para o log.

Conteúdo oficial AivyroAlinhado ao contrato público atual

HTTP	type	Quando
400	invalid_request_error	Corpo ou query inválidos
401	authentication_error	Chave ausente, inválida ou revogada
403	permission_error	Falta escopo REST
404	not_found_error	Id desconhecido, outro tenant ou path fora do catálogo
429	rate_limit_error	Acima do limite da chave
500	api_error	Inesperado. Retry de create com a mesma idempotency key
503	api_error	Downstream indisponível. Writes de webhook também usam isto quando o plano de entrega está off

Retry 429 e 500 (com idempotência nas escritas). Não fique em loop em 400/401/403/404. 503 em webhook é “plano de entrega off”, não “tente até aparecer uma linha”.

error

{
  "error": {
    "type": "not_found_error",
    "code": "resource_not_found",
    "message": "This resource is not available on the public REST API",
    "request_id": "req_…"
  }
}