Todos los errores de la API devuelven un cuerpo JSON con un campo error. Una respuesta 4xx suele exigir corregir la solicitud, la cuenta o el límite; una 5xx es del servidor o temporal, pero la seguridad del reintento sigue dependiendo de la acción.
| Código | Nombre | Significado |
|---|---|---|
| 400 | Bad Request | La validación falló porque falta un valor obligatorio, está mal formado, no es compatible o queda fuera del rango permitido. Corrige la solicitud antes de reintentar. |
| 403 | Forbidden | La clave o la cuenta no tiene permiso para realizar esta acción, por ejemplo si la cuenta está suspendida. Reintentar sin cambios no ayudará. |
| 404 | Not Found | No se encontró el recurso API solicitado o no está disponible para esta clave. Verifica el identificador y la pertenencia a la cuenta antes de reintentar. |
| 409 | Conflict | La solicitud entra en conflicto con el estado existente, por ejemplo al reutilizar un request_id de add para otro pedido lógico. Usa la solicitud original o un identificador único nuevo, según corresponda. |
| 413 | Content Too Large | El cuerpo de la solicitud es demasiado grande. Reduce la carga o divide las solicitudes por lotes compatibles antes de reintentar. |
| 429 | Too Many Requests | Un límite de tasa o acción rechazó la solicitud. Revisa X-RateLimit-DeniedBy cuando esté presente y espera el número relativo de segundos indicado por X-RateLimit-Reset. |
| 500 | Internal Server Error | Ocurrió un fallo inesperado del servidor. No supongas que es seguro repetir cualquier escritura; sigue las pautas de reintento y reconciliación específicas de la acción. |
| 502 | Bad Gateway | El proveedor rechazó la solicitud de prestación. Revise la disponibilidad del servicio y los datos de la solicitud antes de reintentar. |
| 503 | Service Unavailable | La API o una operación necesaria no está disponible temporalmente, incluso cuando no hay un proveedor elegible (provider_not_found). Reintenta más tarde con espera progresiva, respeta Retry-After cuando esté presente y conserva el mismo identificador de idempotencia cuando la acción lo admita. |
{
"error": "Missing required parameter: service"
}La acción requiere un parámetro que no se incluyó. Añádelo al cuerpo de la petición y reintenta.
{
"error": "Invalid API key"
}Clave incorrecta, revocada o ausente. Comprueba que el valor coincide con el que se muestra en /dashboard/api. El error es idéntico para claves ausentes y no válidas, para evitar ataques de enumeración.
{
"error": "Insufficient balance"
}El saldo de tu cuenta está por debajo del cargo total del pedido. Recarga mediante /dashboard/wallet o aplica un cupón.
{
"error": "Service not found"
}El ID del servicio no existe. Vuelve a obtener el catálogo con action=services y elige un ID vigente; los servicios discontinuados usan otro error 400.
{
"error": "Rate limit exceeded"
}Un límite de tasa o acción rechazó la solicitud. Revisa X-RateLimit-DeniedBy cuando esté presente y espera el número relativo de segundos de X-RateLimit-Reset.
{
"error": "language must be one of en, es, pt, ru, tr, ar, hi, id, fr, zh",
"error_code": "INVALID_LANGUAGE"
}services y catalog solo aceptan en, es, pt, ru, tr, ar, hi, id, fr o zh. Corrige el valor de idioma antes de volver a intentarlo.
Reintente action=add con el mismo request_id y la misma solicitud lógica para evitar un duplicado; use un valor único nuevo para otro pedido. Las acciones de lectura pueden repetirse con seguridad. Los reintentos de cancelación son seguros mientras el pedido siga siendo apto.