API cloud
Errores y límites de tasa
Formato de errores, códigos de estado y cabeceras de límite de tasa de la API cloud de zn.
Los errores devuelven JSON con un mensaje en error. Los errores de cuota añaden un code legible por máquina.
{"error": "Invalid API key"}{"error": "Monthly call limit reached", "code": "MONTHLY_LIMIT_REACHED"}Códigos de estado
| Estado | Significado | Qué hacer |
|---|---|---|
| 400 | Falta input en el cuerpo, o input supera los 20.000 caracteres |
Envía {"input": "..."} y divide las entradas largas |
| 401 | Clave de API ausente o no válida | Revisa la cabecera Authorization y la clave en el panel |
| 429 | Límite mensual alcanzado (MONTHLY_LIMIT_REACHED) |
Espera lo que indique Retry-After, añade créditos o mejora tu plan |
| 500 | Fallo inesperado en el análisis | Reintenta una vez con espera (cada petición cuenta en la cuota) |
Toma decisiones según el estado HTTP y code, no según el texto de error, que puede cambiar.
Cabeceras de límite de tasa
RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset se devuelven en las respuestas correctas y en los 401 y 429, para que puedas reducir el ritmo antes de llegar a un 429. Un 429 incluye además Retry-After.
¿Fallar en abierto o en cerrado?
Decide qué hace tu agente cuando zn no está disponible. Para herramientas de alto impacto (shell, pagos, borrado de datos), falla en cerrado: no ejecutes la herramienta. Para lecturas de bajo impacto, puedes fallar en abierto y mantener las reglas locales de zn-gate como respaldo.