Errores
Cada error del gateway de Starmodel devuelve un cuerpo JSON estructurado con un code estable. Ramifica según code, no según el message legible.
Formato de error
Todos los errores comparten un mismo envoltorio:
{ "error": { "code": "insufficient_credits", "message": "Insufficient credits. Please top up and try again.", "type": "error" }}El endpoint compatible con Anthropic /v1/messages devuelve los errores en el formato propio de Anthropic — un type: "error" de nivel superior con un objeto error anidado que contiene type y message.
Errores comunes
| Estado | Código | Significado |
|---|---|---|
401 | unauthorized | API key ausente, no válida o desactivada. |
403 | model_not_allowed | La API key no tiene permiso para llamar al modelo solicitado. |
400 | invalid_model | El valor de model no es un id de modelo conocido. |
400 | no_available_channel | No hay ningún canal upstream disponible para este modelo en este momento. |
402 | insufficient_credits | El saldo de la cartera es demasiado bajo para cubrir la solicitud. |
402 | subscription_quota_exceeded | La cuota de tokens de la suscripción para este ciclo se ha agotado. |
400 | model_pricing_missing | El modelo no tiene un precio de venta publicado y aún no se puede facturar. |
429 | rpm_exceeded | Límite de solicitudes por minuto superado. |
429 | tpm_exceeded | Límite de tokens por minuto superado. |
429 | concurrency_exceeded | Demasiadas solicitudes concurrentes. |
502 | upstream_error | El proveedor upstream devolvió un error. |
500 | internal | Error inesperado del gateway — reintenta y contacta con soporte si persiste. |
Límites de tasa y reintentos
Las respuestas 429 incluyen una cabecera Retry-After (en segundos) — espera ese tiempo antes de reintentar. rpm_exceeded / tpm_exceeded son límites por minuto de solicitudes / tokens; concurrency_exceeded significa demasiadas solicitudes en curso a la vez.
Facturación y precios
Un 402 significa que el saldo no cubre la solicitud — recarga (insufficient_credits) o espera al siguiente ciclo (subscription_quota_exceeded). Los códigos 400 model_pricing_* / model_not_billable indican que el modelo aún no tiene un precio de venta publicado; contacta al administrador para configurarlo y publicarlo.
Manejo de errores
Lee error.code para ramificar en el código — es estable. error.message es para personas y puede cambiar. Reintenta 429 y 502 con backoff; no reintentes errores 4xx de facturación o validación sin cambiar antes la solicitud.