Errores

Comprende las respuestas de error, los códigos de estado y los reintentos seguros de Webway.

Los errores usan un pequeño envoltorio JSON que los SDK compatibles con OpenAI pueden analizar:

json

{
  "error": {
    "message": "insufficient credit",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

type es el valor general que usan las bibliotecas cliente para decidir cómo actuar. code es más preciso y solo difiere de type cuando el fallo procede de un proveedor.

El envoltorio depende del endpoint. /v1/messages devuelve el formato de Anthropic, por lo que los SDK de Anthropic y Claude Code pueden analizarlo y aplicar su propia lógica de reintento sin tratar esta pasarela como un caso especial:

json

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "the provider is over capacity, retry shortly (request 4f2ab910)",
    "code": "overloaded"
  }
}

Códigos de estado

Estado	Significado	¿Reintentar?
`400`	JSON, campos o parámetros no válidos	No; corrige la solicitud
`401`	Clave ausente, no válida, caducada o revocada	No; sustituye la clave
`402`	Tu saldo no alcanza para cubrir la solicitud	Después de añadir saldo
`403`	El modelo requiere tu propia clave del proveedor	No; añade una en el panel
`404`	No se encontró el modelo o el endpoint	No; comprueba el ID y la ruta
`413`	El cuerpo de la solicitud es demasiado grande	No; reduce la carga útil
`429`	Se alcanzó el límite de solicitudes	Sí; espera y vuelve a intentarlo
`502` / `503`	El proveedor no está disponible	Sí; usa una espera progresiva
`504`	Se agotó el tiempo de espera del proveedor	Sí; usa una espera progresiva

402 siempre se refiere únicamente a tu saldo. Un problema de facturación entre Webway y un proveedor es un 502, porque no puedes hacer nada al respecto.

Fallos del proveedor

Cuando el fallo procede de un proveedor y no de tu solicitud, code indica cuál fue:

`code`	Estado	Significado	¿Reintentar?
`model_unavailable`	`502`	El proveedor no sirve este modelo. Nos corresponde solucionarlo	No
`context_length_exceeded`	`400`	La solicitud supera la ventana de contexto del modelo	No
`content_filtered`	`400`	La capa de seguridad del proveedor la rechazó	No
`invalid_request`	`400`	El proveedor rechazó la solicitud	No
`rate_limited`	`429`	El proveedor aplicó un límite de solicitudes	Sí
`overloaded`	`503`	El proveedor ha superado su capacidad	Sí
`timeout`	`504`	El proveedor no respondió a tiempo	Sí
`transport_error`	`502`	Falló la conexión con el proveedor	Sí
`upstream_error`	`502`	Sin clasificar. Siempre se investiga	Quizá

El texto de error del proveedor nunca se transmite directamente. Los servicios de origen describen los fallos con su propio vocabulario, a veces en otro idioma, suelen mencionar infraestructura que no te pertenece y ese texto cambia sin previo aviso. Cada fallo se clasifica dentro del conjunto anterior y se reescribe, de modo que el mensaje que recibes es lo bastante estable para usarlo en tus registros.

Cada mensaje termina con un ID de solicitud de Webway. Inclúyelo en las solicitudes de soporte: es el identificador que realmente se puede consultar.

Errores durante la transmisión

Una solicitud puede fallar después de que ya se hayan enviado los encabezados de respuesta. En ese momento ya no es posible cambiar el código de estado, por lo que el fallo llega como un evento del flujo, con el mismo protocolo que el resto: event: error en /v1/messages, un evento error en /v1/responses y un fragmento error en /v1/chat/completions. Los valores de code son los de la misma tabla.

Trata como un fallo cualquier flujo que termine sin su evento final, no como una respuesta corta.

Reglas de reintento

Reintenta únicamente las respuestas 429 y los errores transitorios 5xx. Usa una espera exponencial con variación aleatoria, limita el número de intentos y respeta Retry-After cuando esté presente.

No reintentes sin cambios las respuestas 400, 401, 402, 403, 404 ni 413. La misma solicitud volverá a fallar.

Las solicitudes rechazadas antes de que el proveedor empiece a trabajar no se cobran. Una solicitud que falle después de iniciarse la generación puede cobrar los tokens ya generados, incluida una que canceles durante la transmisión.