Documentação da APIDocumentação da API
Erros
Envelopes de erro estáveis, códigos e status HTTP
Os erros usam um envelope fixo e nunca contêm diagnósticos privados:
{
"success": false,
"error": {
"code": "INVALID_REQUEST",
"message": "The request is invalid.",
"request_id": "req_012345"
}
}| HTTP | Código | Significado |
|---|---|---|
| 400 | INVALID_REQUEST | corpo, campo de formulário, cabeçalho ou imagem inválidos |
| 400 | CONTENT_POLICY_VIOLATION | a requisição não pode ser processada |
| 401 | UNAUTHORIZED | chave de API ausente ou inválida |
| 402 | INSUFFICIENT_CREDITS | saldo disponível insuficiente |
| 403 | FORBIDDEN | falta o escopo necessário ou o acesso beta |
| 404 | JOB_NOT_FOUND | job inexistente ou de outra conta |
| 409 | IDEMPOTENCY_CONFLICT | chave reutilizada com conteúdo diferente |
| 409 | JOB_CANCELED | o job foi cancelado |
| 429 | RATE_LIMIT_EXCEEDED | limite de requisições excedido |
| 500 | JOB_FAILED | o job de imagem não pôde ser concluído |
| 500 | INTERNAL_ERROR | a requisição não pôde ser concluída |
A rejeição por tamanho de upload usa HTTP 413 com INVALID_REQUEST. Trate
429 e jobs não terminais como passíveis de retentativa, respeitando o atraso
documentado. Para os demais erros, ajuste a requisição ou fale com o suporte
informando o request_id; não faça parsing da mensagem destinada a pessoas na
lógica do programa.