Errores y límites
Cada fallo utiliza un único sobre. El código es estable; el mensaje es un texto de reserva en inglés que puedes mostrar a un usuario.
{
"error": {
"code": "insufficient_credits",
"message": "You need more credits to generate."
}
}Estados
| HTTP | Código típico | Qué hacer |
|---|---|---|
| 400 | invalid_request, prompt_too_long, invalid_reference_image | Corrige la solicitud; no reintentes sin cambios |
| 401 | unauthorized | Comprueba la clave; no reintentes en bucle |
| 402 | insufficient_credits | Recarga créditos; nunca reintentes |
| 403 | unauthorized | Creación de claves impagas, o audio solicitado sin premium |
| 404 | not_found | Trabajo desconocido, o no pertenece a esta cuenta |
| 409 | invalid_request | Idempotency-Key en conflicto; usa una clave nueva |
| 413 / 415 | invalid_request / unsupported_image_type | Sube un JPEG, PNG o WebP más pequeño |
| 429 | rate_limited | Espera Retry-After |
| 500 / 503 | internal | Reintentar con retroceso exponencial |
400
- Código típico
invalid_request,prompt_too_long,invalid_reference_image- Qué hacer
- Corrige la solicitud; no reintentes sin cambios
401
- Código típico
unauthorized- Qué hacer
- Comprueba la clave; no reintentes en bucle
402
- Código típico
insufficient_credits- Qué hacer
- Recarga créditos; nunca reintentes
403
- Código típico
unauthorized- Qué hacer
- Creación de claves impagas, o audio solicitado sin premium
404
- Código típico
not_found- Qué hacer
- Trabajo desconocido, o no pertenece a esta cuenta
409
- Código típico
invalid_request- Qué hacer
Idempotency-Keyen conflicto; usa una clave nueva
413 / 415
- Código típico
invalid_request/unsupported_image_type- Qué hacer
- Sube un JPEG, PNG o WebP más pequeño
429
- Código típico
rate_limited- Qué hacer
- Espera
Retry-After
500 / 503
- Código típico
internal- Qué hacer
- Reintentar con retroceso exponencial
Una generación fallida es una respuesta de trabajo 200 con status: "failed" y un objeto error con el código internal. Un trabajo finalizado es terminal: no lo envíes de nuevo.
Política de reintentos
- Reintenta solo las respuestas HTTP
429,timeouteinternal. - Nunca reintentes
insufficient_credits, y nunca reenvíes un trabajo que ya terminó comofailed. - Usa una
Idempotency-Keyen las creaciones para que un reintento no pueda cobrar dos veces. - Retrocede de forma exponencial, con jitter, empezando alrededor de un segundo.
Límites de velocidad
Los límites son por clave, en ventanas fijas de un minuto, salvo que se indique lo contrario. Valores predeterminados:
- 60 solicitudes/minuto en total.
- 10 generaciones por minuto.
- 5 subidas/minuto.
- 120 solicitudes
GET /v1/models/minuto por IP de cliente (la ruta es pública). - 5 creaciones de clave API por hora por cuenta.
Un 429 incluye X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset y Retry-After.
Disponibilidad
Si /v1 no está disponible temporalmente, cada ruta responde 503 con el código internal. Reintenta más tarde con retroceso exponencial.