Límites y códigos de error
La API usa códigos de estado HTTP estándar. El cuerpo del error sigue el formato del cliente que uses, así que los SDK de OpenAI y Anthropic pueden leerlo tal cual.
Formato de los errores
Los endpoints con formato OpenAI devuelven un objeto error con message, type y code. Los endpoints con formato Anthropic devuelven "type": "error" con un objeto error que contiene type y message. Los errores que se producen en mitad de un stream se envían como un evento con la misma forma.
402
{
"error": {
"message": "GeraiPoints tidak cukup, silakan top up",
"type": "insufficient_quota",
"code": "insufficient_quota"
}
}El contenido de
message está escrito en indonesio y puede cambiar. Para la lógica del programa, comprueba el código de estado HTTP y type/code, no el texto del mensaje.Códigos de estado
| Estado | type / code | Significado | Qué hacer |
|---|---|---|---|
| 400 | invalid_request_error | Solicitud no válida: el cuerpo no es JSON, model está vacío o messages falta o está vacío. También aparece si la URL base es incorrecta y la ruta queda como /v1/v1/…. | Revisa el cuerpo y la URL base. |
| 401 | authentication_error | La clave API no se envió, es incorrecta o ha sido revocada, o se usó en la vía equivocada (clave bansos en un endpoint de pago, o viceversa). | Comprueba la clave y la URL base — Autenticación. |
| 402 | insufficient_quota | No hay suficientes GeraiPoints para esta solicitud. | Recarga GeraiPoints y vuelve a enviar. |
| 403 | permission_error | El modelo no está en la allowlist de esta clave, o es un modelo exclusivo de un plan que aún no tienes. | Añade el modelo a la allowlist de la clave o usa otra clave. |
| 404 | model_not_found | Id de modelo desconocido o no disponible por ahora. Los nombres con prefijo, como gp/… u openai/…, también dan 404. | Copia el id exacto de la lista de modelos. |
| 413 | — | El cuerpo de la solicitud es demasiado grande para que el servidor lo acepte. | Resume el historial de la conversación o reduce los adjuntos. |
| 429 | rate_limit_error | Demasiadas solicitudes: la capacidad del modelo está llena o se ha superado el límite del plan Unlimited/Bansos. | Espera lo que indique Retry-After (si existe) y vuelve a intentarlo con pausas. |
| 502 | api_error | El servicio del modelo está ocupado o tiene problemas; la solicitud no se factura. | Vuelve a intentarlo en unos segundos o usa otro modelo. |
| 503 | api_error | El modelo está en mantenimiento o no está disponible temporalmente; la solicitud no se factura. | Vuelve a intentarlo más tarde o usa otro modelo. |
Límites de uso
| Tipo | Límite |
|---|---|
| Clave de pago (gk-) | Sin límite de frecuencia fijo por clave; el uso está limitado por el saldo de GeraiPoints. El 429 solo aparece cuando la capacidad del modelo está llena. |
| Plan Unlimited | Límite de solicitudes por minuto y de solicitudes simultáneas por cuenta. Las respuestas 429 incluyen Retry-After y x-ratelimit-*. Detalles en la página Unlimited. |
| Nivel gratuito (Bansos) | Cupo de solicitudes por día y límite por minuto. Las respuestas 429 incluyen Retry-After y x-ratelimit-*. Cupo restante en la página Bansos. |
| Tamaño y respuesta | Los cuerpos demasiado grandes se rechazan con 413. La longitud de la respuesta (max_tokens) puede reducirse automáticamente si el saldo no alcanza para el valor solicitado. |
| Clave API | Máximo 20 claves activas por cuenta; allowlist de hasta 64 modelos por clave. |
| Claves de clientes | Los límites se aplican antes de procesar: una solicitud que superaría el límite restante se rechaza. Límite único agotado → 402 KEY_BATAS_HABIS (sube el límite para añadir cuota); límite diario/mensual alcanzado → 429 KEY_BATAS_HARIAN / KEY_BATAS_BULANAN con Retry-After. Clave pausada → 403 KEY_DIJEDA. Los modelos -unli y bansos no se pueden usar con claves de cliente. |
Reintentar correctamente
- Reintenta solo con 429, 502 y 503, con pausas cada vez más largas (p. ej. 1, 2, 4, 8 segundos) y un máximo de 2–3 intentos.
- No reintentes 400, 401, 402, 403 ni 404: corrige antes la solicitud; el resultado será el mismo.
- Respeta la cabecera
Retry-Aftersi existe. - Cada reintento es una nueva solicitud facturada. Si la causa es el timeout de la app, auméntalo — consulta Configuración de herramientas agénticas.