Errors & Rate Limits

The Armox Public API uses standard HTTP status codes and a consistent JSON error shape.

Error Response Format

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

Examples:

{ "error": "Invalid API key" }

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

Error Codes

Rate Limits

Rate limiting is enforced per API key using a rolling 60-second window.

Every successful authenticated response includes:

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

If limit is exceeded, API returns:

• status 429
• error body { "error": "Rate limit exceeded" }
• Retry-After: 60 header

Handling 429 Responses

Recommended strategy:

1. read Retry-After header
2. wait before retrying
3. use exponential backoff with jitter for repeated 429s
4. avoid synchronized retries across workers

JavaScript Retry Example

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");
}

Credits and Billing Behavior

• credits are charged when a run is accepted
• failed jobs are refunded by the execution flow
• monitor usage via GET /api/v1/account

Common Production Errors

• Invalid API key: wrong/expired/revoked key
• Public API access requires ...: subscription not eligible
• Insufficient credits ...: top up credits or reduce run cost
• Rate limit exceeded: add backoff + queueing

Debugging Checklist

• verify Authorization: Bearer ... is present
• verify endpoint path and method
• log request IDs/job IDs in your app
• capture response headers for rate-limit observability
• persist failed payloads for replay

Related Pages

• Authentication
• Jobs Endpoint
• Account Endpoint