Errores y Límites de Tasa

La API Pública de Armox utiliza códigos de estado HTTP estándar y un formato JSON de error consistente.

Formato de Respuesta de Error

{ "error": "Human-readable message" }

Ejemplos:

{ "error": "Invalid API key" }

{ "error": "Insufficient credits. Required 1000, available 200" }

Códigos de Error

Código	Significado	Causa Típica
`400`	Bad Request	Payload inválido, campo obligatorio faltante, modelo inválido
`401`	Unauthorized	Clave API Bearer faltante o inválida
`402`	Payment Required	Créditos insuficientes
`403`	Forbidden	Restricciones de plan/acceso
`404`	Not Found	Recurso/job/app no encontrado
`409`	Conflict	El job no puede ser cancelado en su estado actual
`429`	Too Many Requests	Límite de tasa por clave excedido
`500`	Internal Server Error	Fallo inesperado del backend

Límites de Tasa

Los límites de tasa se aplican por clave API usando una ventana móvil de 60 segundos.

Cada respuesta autenticada exitosa incluye:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Si se excede el límite, la API devuelve:

estado 429
cuerpo de error { "error": "Rate limit exceeded" }
encabezado Retry-After: 60

Manejo de Respuestas 429

Estrategia recomendada:

lee el encabezado Retry-After
espera antes de reintentar
usa retroceso exponencial con jitter para 429s repetidos
evita reintentos sincronizados entre workers

Ejemplo de Reintento en JavaScript

async function requestWithRetry(url, options, retries = 3) {
  for (let attempt = 0; attempt <= retries; attempt += 1) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;

    const retryAfter = Number(response.headers.get("Retry-After") || 2);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
  }

  throw new Error("Exceeded retry attempts");
}

Créditos y Comportamiento de Facturación

los créditos se cobran cuando se acepta una ejecución
los jobs fallidos se reembolsan mediante el flujo de ejecución
monitorea el uso a través de GET /api/v1/account

Errores Comunes en Producción

Invalid API key: clave incorrecta/expirada/revocada
Public API access requires ...: suscripción no elegible
Insufficient credits ...: recarga créditos o reduce el costo de ejecución
Rate limit exceeded: añade retroceso + cola de solicitudes

Lista de Verificación para Depuración

verifica que Authorization: Bearer ... esté presente
verifica la ruta y el método del endpoint
registra los IDs de solicitudes/jobs en tu aplicación
captura los encabezados de respuesta para observabilidad de límites de tasa
persiste los payloads fallidos para reenvío