Documentación de la APIDocumentación de la API
Errores
Envolturas de error estables, códigos y estados HTTP
Los errores usan una envoltura fija y nunca contienen 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 | cuerpo, campo de formulario, cabecera o imagen no válidos |
| 400 | CONTENT_POLICY_VIOLATION | la petición no se puede procesar |
| 401 | UNAUTHORIZED | falta la clave de API o no es válida |
| 402 | INSUFFICIENT_CREDITS | el saldo disponible es insuficiente |
| 403 | FORBIDDEN | falta el ámbito requerido o el acceso beta |
| 404 | JOB_NOT_FOUND | el trabajo no existe o pertenece a otra cuenta |
| 409 | IDEMPOTENCY_CONFLICT | la clave se reutilizó con contenido distinto |
| 409 | JOB_CANCELED | el trabajo se canceló |
| 429 | RATE_LIMIT_EXCEEDED | se superó el límite de peticiones |
| 500 | JOB_FAILED | el trabajo de imagen no pudo completarse |
| 500 | INTERNAL_ERROR | la petición no pudo completarse |
El rechazo por tamaño de subida usa HTTP 413 con INVALID_REQUEST. Trata
429 y los trabajos no terminales como reintentables respetando el retardo
documentado. Para el resto de errores, cambia la petición o contacta con soporte
indicando request_id; no analices el mensaje destinado a personas dentro de la
lógica del programa.