14Referencia
Códigos de error
Todos los errores de la API llegan en el mismo formato. Basa la lógica en el estado HTTP, el código y los campos de details, y muestra a la persona el texto de message.
Formato del error
Un error es un JSON con un objeto error de tres campos:
- code
- Un código estable con el formato
ERR_…. Úsalo para decidir qué hacer. - message
- Texto para mostrar a una persona. Está en inglés y su redacción puede cambiar: no lo analices con código.
- details
- Detalles: qué falla exactamente y qué corregir. El campo puede estar vacío.
HTTP/1.1 400 Bad Request { "error": { "code": "ERR_INVALID_REQUEST", "message": "The reference image is no longer available. Upload the file again.", "details": { "reason": "reference_unavailable", "input_index": 0, "retryable": false } } }
Un cuerpo que no es un JSON válido y una carga multipart sin el campo obligatorio se rechazan con 422 y un cuerpo con la forma {"detail": […]}. No se hace ningún cargo. No los confundas con ERR_INPUT_FETCH_FAILED: también llega con 422, pero en el formato habitual.
Referencia de códigos
Las filas se pueden filtrar por estado y buscar por palabra. Las respuestas 429 y 503 incluyen el encabezado Retry-After, en segundos.
| Código | HTTP | Qué significa y qué hacer |
|---|---|---|
ERR_INVALID_REQUEST | 400 | La solicitud no se puede ejecutar así. Lee error.message y error.details, corrige la solicitud y envíala de nuevo. No se hizo ningún cargo. |
ERR_CONTENT_POLICY | 400 | Código reservado. El rechazo por las reglas de seguridad se determina después de aceptar la solicitud y llega como una tarea con estado failed y failure.code: content_policy. |
ERR_API_KEY_INVALID | 401 | No hay clave o no se reconoce: details.reason es api_key_missing o api_key_invalid. Revisa la clave, Claves y acceso. |
ERR_INSUFFICIENT_BALANCE | 402 | No hay saldo suficiente o se agotó el límite mensual de la clave o de la cuenta. Saldo. |
ERR_ACCOUNT_DISABLED | 403 | La clave es correcta, pero la cuenta está desactivada. Escribe a soporte. |
ERR_API_SUSPENDED | 403 | El acceso de la cuenta a la API está suspendido. Deja de enviar solicitudes y escribe a soporte; el portal sigue disponible. |
ERR_MODEL_NOT_FOUND | 404 | Tu cuenta no tiene ese modelo. La lista está en GET /models. |
ERR_NOT_FOUND | 404 | No se encuentra la tarea o pertenece a otra cuenta. Comprueba el id. |
ERR_RATE_LIMIT | 429 | Solicitudes demasiado frecuentes, sondeo de una tarea más de una vez cada 5 segundos, límite diario de cargas de una cuenta nueva o bloqueo tras errores de acceso. Espera Retry-After segundos, Límites. |
ERR_QUOTA_EXCEEDED | 429 | Demasiadas tareas en curso, o se envió a la vez la misma clave de idempotencia. Espera y repite con los mismos identificadores. |
ERR_INPUT_FETCH_FAILED | 422 | No se pudo descargar ni comprobar la imagen de referencia antes de la generación y del cargo. Reintenta solo si details.retryable = true; en caso contrario, sustituye la imagen de referencia. |
ERR_GENERATION_FAILED | 500 | No se pudo iniciar ni completar la generación. El importe cargado se devuelve solo. details.reason = pricing_unavailable — no se pudo determinar el precio antes del cargo: inténtalo más tarde. |
ERR_PROVIDER_UNAVAILABLE | 503 | No disponible temporalmente. Espera Retry-After, mira details.reason y limita el número de reintentos. |
ERR_INTERNAL | 500, 503 | Error interno, 500 o 503. 500 no indica si la solicitud se aceptó: antes de reintentar, comprueba la tarea con la misma clave de idempotencia. El cargo de una solicitud que no creó nada se devuelve por sí solo. 503 llega con Retry-After. |
Errores de acceso
Estas respuestas son comunes a todos los endpoints que usan clave. No repitas la solicitud con la misma clave: los 401 y 403 repetidos desde una misma dirección IP provocan un bloqueo temporal (más información: Límites). Cómo guardar y cambiar las claves: Claves y acceso.
| Qué pasó | Respuesta | Qué hacer |
|---|---|---|
| La solicitud no lleva clave | 401 ERR_API_KEY_INVALID details.reason = api_key_missing; message: «no API key on the request» | Envía la clave en el encabezado Authorization o X-API-Key |
| La clave no se reconoce | 401 ERR_API_KEY_INVALID details.reason = api_key_invalid; message: «API key not recognized» | Comprueba que la clave esté copiada completa y que no se haya revocado en el portal |
| Cuenta desactivada | 403 ERR_ACCOUNT_DISABLED details.reason = account_disabled; message: «this account is disabled» | Deja de enviar solicitudes y escribe a soporte |
| Acceso a la API suspendido | 403 ERR_API_SUSPENDED details.reason = api_suspended; message: «API access is paused for this account by its account manager» | Deja de enviar solicitudes y escribe a soporte; el portal sigue disponible |
Errores de la solicitud
Estos rechazos llegan antes del cargo. La generación no empieza y no se gasta dinero.
| Qué pasó | Respuesta | Qué hacer |
|---|---|---|
| La imagen de referencia no está disponible | 400 ERR_INVALID_REQUEST details.reason = reference_unavailable, details.input_index es la posición de la imagen de referencia, contando desde cero | Vuelve a subir el archivo y sustituye el file_id. Repetir con el mismo archivo no ayuda |
| La imagen de referencia no se puede descargar | 422 ERR_INPUT_FETCH_FAILED details.reason = input_fetch_failed, details.retryable | Con retryable: true, repite más tarde; en caso contrario, sustituye la imagen de referencia |
| El formato de la imagen de referencia no es válido | 400 ERR_INVALID_REQUEST «Unsupported image format. Supported formats: PNG, JPEG, WebP.» | Vuelve a guardarla en PNG, JPEG o WebP, Imágenes de referencia |
| Prompt vacío | 400 ERR_INVALID_REQUEST details.fields: ["prompt"] | Envía la descripción de la imagen, aunque haya imágenes de referencia |
| Máscara en la solicitud | 400 ERR_INVALID_REQUEST en details.fields: mask o mask_file_id | Las máscaras no se admiten. Pasa la imagen original como referencia y describe el cambio en el prompt |
| Resolución o relación de aspecto no válidas | 400 ERR_INVALID_REQUEST details.supported es la lista de los valores admitidos | Elige de la lista, Modelos y parámetros |
| No existe esa combinación para la cuenta | 400 ERR_INVALID_REQUEST details.reason = provider_policy_no_route | Cambia la resolución o la relación de aspecto, o escribe a soporte |
Rechazos temporales
503 significa que ahora no se puede aceptar la solicitud. Mira details.reason:
details.reason | Qué significa | Dinero |
|---|---|---|
overloaded | El servicio está sobrecargado y se rechazó la solicitud. Repite más tarde | No hay cargo |
no_provider_enabled | La configuración solicitada no está disponible ahora para la cuenta. Espera y escribe a soporte si el rechazo se repite | No hay cargo |
provider_unavailable | No se pudo iniciar la generación | Si se hizo el cargo, el importe se devuelve por sí solo |
A veces llega 503 ERR_INTERNAL con details vacío: un servicio dependiente no está disponible temporalmente. Un 5xx por sí solo no indica si la solicitud se aceptó: comprueba la tarea con la clave de idempotencia.
Espera y reintentos
- Las respuestas
429y503incluyenRetry-After, en segundos. Espera como mínimo ese tiempo y, al consultar el estado de las tareas, como mínimo el mayor deRetry-Afterydetails.min_interval_seconds. - Reintenta un número limitado de veces y añade un pequeño retardo aleatorio para que los procesos no llamen a la vez.
- No repitas
400,401,402,403ni404sin cambios: corrige primero la causa. - Si se perdió la respuesta, llegó un
500o se agotó el tiempo de espera, no crees una tarea nueva: repite la misma solicitud con la misma clave de idempotencia (Reintentos sin doble cargo).
La generación se paga por adelantado y, si falla, el dinero se devuelve solo. Un error no confirma el reembolso: el importe se ve en el saldo y en el historial de operaciones del portal.
Errores después de aceptar la tarea
Si la solicitud se aceptó (202) pero la imagen no salió, no es un error HTTP. GET /creations/ responde 200 con el estado failed y la cadena error. El importe vuelve al saldo por sí solo.
"The image or prompt was rejected by the safety filter. Try a different image or rephrase the prompt." "The source image was rejected. Try a different photo." "Generation failed. Please try again." "Nothing was rendered for this request. Describe the image you want in the prompt, or attach the source photo it refers to." "Generation timed out." "The reference image is no longer available. Upload the file again." "Could not download the reference image. Please try again later." "The service is temporarily unavailable. Please try again later." "Generation failed."
- Rechazo por las reglas de seguridad: cambia el prompt o usa otra imagen.
- «Nothing was rendered…»: describe en el prompt la imagen que quieres o adjunta la imagen de referencia a la que se refiere.
- «The reference image is no longer available…»: vuelve a subir el archivo y sustituye el
file_id. - Tiempo de espera agotado, indisponibilidad temporal, fallo general: reintenta un número limitado de veces. Si los fallos se repiten, envía a soporte el
idde la tarea.
Para crear a propósito una imagen nueva después de un failed, usa una clave de idempotencia nueva: la clave anterior no reinicia la tarea, y repetir la solicitud con ella devuelve la respuesta 202 guardada, con el mismo id. Un intento nuevo se paga como de costumbre y se reembolsa si falla.
Causa del fallo para programas
Desde el 24 de septiembre de 2026, una tarea fallida contiene además el objeto failure: en GET /creations/ y en el webhook creation.failed. Solo está presente con status: "failed", así que al interpretarlo trátalo como opcional.
{
"id": "5b0214ae-9e39-460a-820a-f6ae3e24400b",
"status": "failed",
"error": "The image or prompt was rejected by the safety filter. Try a different image or rephrase the prompt.",
"failure": {
"type": "declined",
"code": "content_policy",
"retryable": false
}
}- declined
- La causa está en la propia solicitud: en el prompt, en la imagen de referencia o en los datos de entrada. La misma solicitud dará el mismo resultado: cámbiala.
- error
- La causa está en el servicio. Se puede volver a enviar la misma solicitud si
retryableno esfalse.
| Código | Qué significa y qué hacer | Reintento |
|---|---|---|
content_policy | Las reglas de seguridad rechazaron el prompt o la imagen de referencia. Cambia el prompt o usa otra imagen | no |
source_image_rejected | Se rechazó la imagen de referencia. Usa otra imagen | no |
no_image_output | El modelo respondió con texto en lugar de una imagen, por ejemplo la describió con palabras, o el prompt se refiere a una imagen que no se adjuntó. Describe la imagen que necesitas o adjunta una imagen | no |
reference_unavailable | La imagen de referencia ya no está disponible. Vuelve a subirla y sustituye el file_id | no |
invalid_request | La solicitud no se puede ejecutar así, por ejemplo, el modelo no genera la relación de aspecto elegida. Corrige la solicitud | no |
| Código | Qué significa y qué hacer | Reintento |
|---|---|---|
timeout | Se agotó el tiempo de generación. Repite | sí |
unavailable | El servicio no estuvo disponible por un tiempo. Repite más tarde | sí |
reference_fetch_failed | No se pudo descargar la imagen de referencia. Repite más tarde | sí |
internal | Otro fallo en el servicio. Repite más tarde | sí |
Basa la lógica en failure.type y failure.code, no en el texto de error: es para mostrar y su redacción puede cambiar. La lista de códigos está cerrada por ahora, pero pueden aparecer códigos nuevos: trata un código desconocido según su failure.type.
Una solicitud fallida es gratis: el importe vuelve de inmediato al saldo.
Esto se aplica a ambos tipos: tanto a declined como a error.
Preguntas frecuentes
¿Qué error es definitivo y cuál se debe reintentar?
429, 503 y 500 (este último, con cuidado, con la misma clave de idempotencia), y también las tareas con failure.retryable distinto de false. Los 4xx, salvo 429, corrígelos primero.¿Se devuelve el dinero si llega un error?
¿Por qué el texto del error está en inglés?
message y la cadena error son iguales para todos los clientes y pueden cambiar. Para la lógica usa el código, el estado y failure, y muestra a la persona tu propio texto.¿Qué hacer si el error se repite?
id de la tarea o la hora de la solicitud. No hace falta enviar la clave de API ni el prompt.