0xConnect

Errors & retries

The Aion API returns standard HTTP status codes. When you hit a rate limit or temporary failure, check the Retry-After header and back off before retrying.

Error response format

All errors return a JSON object with an error field:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "retryAfterSec": 45
  }
}

HTTP status codes

  • 400 Bad Request — Invalid payload, missing file, or invalid content type
  • 401 Unauthorized — Invalid or missing API key
  • 403 Forbidden — Key lacks required scope or upload doesn't belong to you
  • 404 Not Found — Upload doesn't exist
  • 409 Conflict — Idempotency key already in progress (retry later)
  • 413 Payload Too Large — File exceeds your plan's per-file limit (500 MB on Basic, 1 GB on Pro)
  • 415 Unsupported Media Type — File type is blocked (e.g. executables)
  • 429 Too Many Requests — Rate limit or quota exceeded
  • 502 Bad Gateway — Storage upload failed (temporary, retry)
  • 503 Service Unavailable — Concurrency limit reached (retry)

Retry strategy

When you receive a 409, 429, 502, or 503, check the Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 45

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "retryAfterSec": 45
  }
}

Wait Retry-After seconds before retrying. Ignoring this header may result in longer throttling.

  • 409 idempotency_in_progress — wait for Retry-After, then retry with the same Idempotency-Key
  • 429 rate_limit_exceeded — wait for Retry-After, then retry
  • 502 upload_worker_unavailable — retry with the same Idempotency-Key after Retry-After (or exponential backoff if absent)
  • 503 concurrency_limit_reached — wait for Retry-After, reduce parallel uploads, then retry

Request tracking

Every response includes an X-Request-Id header. Include this ID when contacting support for faster troubleshooting.

Common errors

401 unauthorized

Cause: API key is missing, invalid, or revoked.

Fix: Check your key in the dashboard, regenerate if needed.

403 forbidden

Cause: API key lacks required permissions for this endpoint.

Fix: Create a new key with full permissions.

409 idempotency_in_progress

Cause: A request with this Idempotency-Key is already being processed.

Fix: Wait for Retry-After seconds, then retry with the same key.

413 size_limit_exceeded

Cause: File exceeds the per-file limit for your plan (500 MB on Basic, 1 GB on Pro), or storing it would exceed your total storage quota.

Fix: Use a smaller file, free up storage, or upgrade. Both checks run before the body is read, so there is nothing to retry.

415 unsupported_media_type

Cause: The file type is not allowed (e.g. .exe, .bat, .msi).

Fix: Use a supported file type.

429 rate_limit_exceeded

Cause: Too many requests in a short time, or daily quota reached.

Fix: Wait for Retry-After seconds, then retry.

502 upload_worker_unavailable

Cause: The storage network is temporarily unavailable.

Fix: Retry with the same Idempotency-Key after a few seconds.

503 concurrency_limit_reached

Cause: Too many concurrent uploads from this key.

Fix: Wait for Retry-After seconds. Upload sequentially if possible.

Retry best practices

  • Use Idempotency-Key — Prevents duplicate uploads on retry
  • Always check Retry-After — Don't retry immediately
  • Exponential backoff — If no Retry-After, wait 1s, 2s, 4s, 8s…
  • Max retries — Give up after 3–5 attempts to avoid infinite loops
  • Log X-Request-Id — Include in error reports for faster support