Erros e limites
Cada falha usa um único envelope. O código é estável; a mensagem é um fallback em inglês que você pode mostrar a um usuário.
{
"error": {
"code": "insufficient_credits",
"message": "You need more credits to generate."
}
}Status
| HTTP | Código típico | O que fazer |
|---|---|---|
| 400 | invalid_request, prompt_too_long, invalid_reference_image | Corrija a solicitação; não tente novamente sem alterações |
| 401 | unauthorized | Verifique a chave; não tente novamente em loop |
| 402 | insufficient_credits | Recarregar créditos; nunca tentar novamente |
| 403 | unauthorized | Criação de chave não paga, ou áudio solicitado sem premium |
| 404 | not_found | Trabalho desconhecido, ou não pertence a esta conta |
| 409 | invalid_request | Idempotency-Key conflito; use uma chave nova |
| 413 / 415 | invalid_request / unsupported_image_type | Carregue um JPEG, PNG ou WebP menor |
| 429 | rate_limited | Aguarde Retry-After |
| 500 / 503 | internal | Tentar novamente com backoff |
400
- Código típico
invalid_request,prompt_too_long,invalid_reference_image- O que fazer
- Corrija a solicitação; não tente novamente sem alterações
401
- Código típico
unauthorized- O que fazer
- Verifique a chave; não tente novamente em loop
402
- Código típico
insufficient_credits- O que fazer
- Recarregar créditos; nunca tentar novamente
403
- Código típico
unauthorized- O que fazer
- Criação de chave não paga, ou áudio solicitado sem premium
404
- Código típico
not_found- O que fazer
- Trabalho desconhecido, ou não pertence a esta conta
409
- Código típico
invalid_request- O que fazer
Idempotency-Keyconflito; use uma chave nova
413 / 415
- Código típico
invalid_request/unsupported_image_type- O que fazer
- Carregue um JPEG, PNG ou WebP menor
429
- Código típico
rate_limited- O que fazer
- Aguarde
Retry-After
500 / 503
- Código típico
internal- O que fazer
- Tentar novamente com backoff
Uma geração falhada é uma resposta de tarefa 200 com status: "failed" e um objeto error com o código internal. Uma tarefa concluída é terminal: não a envie novamente.
Política de repetição
- Tente novamente apenas respostas HTTP
429,timeouteinternal. - Nunca repita
insufficient_credits, e nunca reenvie um trabalho que já terminou comofailed. - Use uma
Idempotency-Keynas criações para que uma nova tentativa não possa cobrar duas vezes. - Recue exponencialmente, com jitter, começando em cerca de um segundo.
Limites de taxa
Os limites são por chave, em janelas fixas de um minuto, salvo indicação em contrário. Padrões:
- 60 solicitações/minuto no total.
- 10 gerações cria/minuto.
- 5 uploads/minuto.
- 120 solicitações
GET /v1/models/minuto por IP de cliente (a rota é pública). - 5 criações de chave de API/hora por conta.
Um 429 carrega X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset e Retry-After.
Disponibilidade
Se /v1 estiver temporariamente indisponível, cada rota responde 503 com o código internal. Tente novamente mais tarde com backoff.