Errores y límites de tasa
Un sobre de error consistente y códigos de estado predecibles.
Sobre de error
Cada respuesta de error tiene la misma forma:
json{ "error": { "code": "payment_required", "message": "Créditos insuficientes.", "details": null } }
Códigos de estado
| Estado | Código | Significado |
|---|---|---|
| 400 | bad_request | Validación fallida; ver details. |
| 401 | unauthorized | Token faltante o inválido. |
| 402 | payment_required | Sin suficientes créditos, o límite de servidores alcanzado. |
| 403 | forbidden | Endpoint solo para administradores, o alcance de clave insuficiente. |
| 404 | not_found | No existe ese servidor/instancia, o no es tuyo. |
| 409 | conflict | Ningún nodo tiene capacidad para la petición. |
| 429 | rate_limited | Demasiadas peticiones. |
| 502 | upstream_error | A upstream panel returned an error. |
| 500 | internal_error | Error inesperado del servidor. |
Límites de tasa
La API permite 240 peticiones por minuto por cliente. Si se supera, devuelve 429. Los health checks y el documento OpenAPI están exentos. Aplica retroceso exponencial con jitter en un 429.
Detalles de validación
Las respuestas 400 incluyen un objeto details del validador de esquemas que lista los campos incorrectos, para que puedas mostrar mensajes precisos a los usuarios.