Plataforma

Errores

Los errores llegan en JSON con el formato del endpoint que llamaste, con un mensaje escrito para personas y, en los endpoints al estilo OpenAI, un código estable para los programas.

La estructura

Endpoints al estilo OpenAI
{
  "error": {
    "message": "This API key can't use `gpt-6-astra`. It's limited to gpt-6-sol. Change that at https://zurelay.com/app/keys.",
    "type": "permission_error",
    "param": "model",
    "code": "model_not_allowed"
  }
}

En /v1/messages los mismos errores llegan con la forma de Anthropic, que no incluye código: usa el estado HTTP y error.type: { "type": "error", "error": { "type": "...", "message": "..." } }. Toda respuesta de chat, imagen y video, sea un error o no, lleva una cabecera x-request-id.

Códigos

EstadoCódigoQué hacer
400invalid_requestCorrige la solicitud: el mensaje dice qué falla y el parámetro indica dónde.
400unsupported_contentEl modelo no lee ese tipo de archivo. Quítalo o elige un modelo que sí lo haga.
400invalid_urlNo se pudo descargar un enlace de la solicitud. El mensaje incluye el estado con el que respondió.
400invalid_imageNo se pudo usar una imagen de entrada (tipo, tamaño o enlace).
400image_not_generatedEl modelo rechazó el prompt. No se cobra.
400context_length_exceededEl modelo indica que la conversación es demasiado larga para él. Acórtala o elige un modelo con un contexto mayor.
400max_tokens_reachedUna respuesta no streaming de /v1/messages alcanzó tu max_tokens en medio de una llamada a herramienta, así que no es un mensaje completo. Se cobra lo generado. Vuelve a enviarla con un max_tokens mayor.
401missing_api_keyEnvía la clave en Authorization o x-api-key.
401invalid_api_keyLa clave es incorrecta o fue revocada.
401expired_api_keyCrea una clave nueva.
402insufficient_quotaEl saldo, menos lo que tus solicitudes en curso han reservado, no cubre esta solicitud, o se agotó a mitad de una respuesta. Añade crédito en Facturación o pide menos salida con un max_tokens menor. Cuando la recarga automática ha iniciado una recarga, el mensaje lo indica: reintenta unos segundos después.
402key_budget_exceededLa solicitud podría llevar la clave por encima de su presupuesto mensual, contando sus solicitudes en curso, o lo alcanzó a mitad. Sube el presupuesto o espera al mes que viene.
402key_daily_budget_exceededLo mismo con el presupuesto diario de la clave. Súbelo o espera a medianoche UTC.
403model_not_allowedLa clave no tiene permitido usar este modelo.
403ip_not_allowedLa clave solo funciona desde otras direcciones.
404model_not_foundConsulta el ID del modelo en la página de modelos.
404unknown_urlNo existe ese endpoint. Revisa la ruta y la URL base.
404video_not_foundNo hay ningún video con ese ID en este espacio de trabajo.
404image_not_foundNo hay ninguna solicitud de imagen con ese ID en este espacio de trabajo (GET /v1/images/{id}, para solicitudes hechas con un callback_url).
409video_not_readyEl video no está terminado: consulta su estado hasta que sea completed.
409video_failedEl video falló, así que no hay nada que descargar. Su error explica por qué.
410video_expiredEl video se eliminó, desde la Biblioteca o tras sus 30 días.
413too_largeLa solicitud o un archivo supera el límite. Envía los archivos grandes como enlaces.
429rate_limit_exceededEspera retry-after segundos y reintenta.
429concurrency_limit_exceededEl espacio de trabajo ya tiene 32 solicitudes en curso a la vez. Reintenta tras retry-after segundos, cuando alguna haya terminado.
500server_errorAlgo salió mal por nuestra parte. Reintenta.
502stream_interruptedSe envía como último evento de un stream que se cortó. Se cobra lo que se transmitió antes del corte, nada después; reintenta.
503model_unavailableEl modelo está caído ahora mismo. Reintenta tras retry-after segundos o activa el enrutamiento inteligente. Sin retry-after y con x-should-retry: false, el modelo está activo pero devuelve un mensaje de error a esta solicitud cada vez: no la reenvíes sin cambios.
503server_restartingZurelay está reiniciando la máquina que tenía tu solicitud. Reintenta de inmediato: otra máquina la tomará. No se cobra, salvo que ya hubiera empezado un stream: entonces se cobra lo que te llegó, como en un stream que se cortó.
503storage_unavailableSe generó una imagen pero no se pudo entregar. No se cobra; reintenta.
503service_unavailableUn problema breve por nuestra parte. Reintenta.

Reintentos

  • Reintenta 429 y 503, esperando los segundos de la cabecera retry-after (o con retroceso exponencial), salvo que la respuesta indique x-should-retry: false.
  • No reintentes otros errores 4xx sin cambios: fallarán igual.
  • Las solicitudes fallidas son gratis, así que reintentar no cuesta nada hasta que una funcione. Un stream que se cortó a medias se cobra por lo que entregó, y el raro 503 con x-should-retry: false por su entrada (ver Facturación).
  • Los SDK oficiales de OpenAI y Anthropic ya reintentan los errores correctos por ti.

Errores a mitad de stream

Los errores que un modelo devuelve sobre tu propia solicitud (un parámetro que no acepta, un prompt demasiado largo para él) llegan con el mensaje y el código del propio modelo, como 400 o 422.

Errores a mitad de stream

Una vez iniciado un stream, un fallo no puede convertirse en un estado HTTP. En su lugar recibes un evento de error final (en el formato del endpoint) y el stream termina. Se te cobra la entrada y la salida que te llegaron antes, nada después. Es poco frecuente: la mayoría de los problemas se detectan y se reintentan antes del primer token.

El mismo tipo de evento termina un stream cuyo saldo o presupuesto de la clave se agota a medias, con insufficient_quota, key_budget_exceeded o key_daily_budget_exceeded. Una solicitud no streaming que se queda sin saldo a medias devuelve lo escrito, cortado como una respuesta que alcanzó max_tokens (finish_reason: "length", o stop_reason: "max_tokens" en /v1/messages), con una cabecera x-zurelay-stopped que indica el código.

¿Tienes dudas o falta algo? Escribe a nuestro equipo de soporte y te responderemos por email, normalmente en menos de un minuto.