Errors

Every SteadyLink API error has the same JSON shape, a standard HTTP status, and a request ID. Use this page to decide whether a failed request should be fixed, retried, or reported, and to find the exact meaning of an error code your integration received.

The S3-compatible API uses S3's XML errors instead; see S3 errors.

Error body#

{
  "code": 403,
  "message": {
    "code": "insufficient_scope",
    "required": "assets:write"
  },
  "requestId": "7d3c1f2e-9a4b-4c6d-8e1f-0a2b3c4d5e6f"
}

Structured messages always have a code, and often a human-readable message inside them:

{
  "code": 429,
  "message": {
    "code": "api_write_limit_exceeded",
    "message": "Rate limit exceeded",
    "retryAfter": 12
  },
  "requestId": "0b9e4d2a-6f1c-4a3e-8d7b-2c5f9e1a4b60"
}

When the request body or query string does not match the route's schema (a missing field, a wrong type, a value out of range), the response is a 400 with the plain message "Validation error" and no field details. Check the request against the route's reference page.

Status codes#

Error codes#

The code inside a structured message, grouped by what caused it.

Access and entitlement#

Entitlement errors also carry message and plan. While a key is rejected for its entitlement, repeated attempts are themselves rate limited (see Rate limits).

Limits and quotas#

These share one shape:

{
  "code": 413,
  "message": {
    "code": "upload_size_limit",
    "resource": "upload_bytes",
    "usage": 262144000,
    "reserved": 0,
    "requested": 262144000,
    "limit": 104857600,
    "resetAt": null,
    "behavior": "hard_stop",
    "upgrade": { "recommendedPlan": "personal", "url": "/dashboard/settings?section=plans" }
  },
  "requestId": "3a8f1c6e-2d4b-4e9a-b7c0-5f1e8d2a6c93"
}

Plan limits are listed in Usage and limits.

Rate-limit codes#

Every rate-limit body includes retryAfter in seconds, matching the Retry-After header.

Rate limits#

API-key limits are pooled per workspace, not per key: creating more keys does not raise them. A request counts against the burst window, then the per-minute read or write window, then the monthly allowance, and, for expensive writes, the per-minute and per-day expensive limits.

A write is expensive when its path contains /upload, /commit, /replace, /purge, /signed-url, or /retry, or when it is any write under /api/conversions. These are the operations that start scans, workers, or storage operations.

Signed-in sessions (the dashboard, or an accessToken) are not subject to the plan table. Their writes are limited per credential to 60 per minute, and delivery and download routes such as /a/{asset_id} allow 600 requests per minute per client when no API key is sent. Sign-in and other authentication routes allow 10 requests per minute per IP address. The S3-compatible API has its own per-key limits.

Response headers#

On a successful request the rate-limit headers describe the per-minute read or write window. On a 429 they describe whichever window was exceeded. Browsers can read all of these headers from cross-origin requests.

Send your own X-Request-Id (for example your trace ID) to find a request in both your logs and SteadyLink's. When you report a problem, include the request ID, the route, the status, and the time. Never include the API key or a signed token.

Retry policy#

Start backoff around 250 ms and double it on each attempt, with random jitter so many clients do not retry at once. Both SDKs do this for you on 429, 502, 503, and 504 (see TypeScript SDK retries and Python SDK retries).

Idempotency keys#

Upload completion (POST /api/upload-sessions/{id}/complete) has an explicit idempotency contract. Send an Idempotency-Key header and reuse it on every retry of the same completion:

• The first completion stores the key. A retry with the same key, or a completion of a session that is already finished, returns the session without doing the work twice.
• A completion with a different key while the session already has one returns 409 Idempotency key mismatch.

For any API-key request, an Idempotency-Key also identifies retries for metering, so a retried request with the same key counts once against the monthly management-operation allowance. It still counts against the per-minute rate limits. Other writes do not deduplicate on the key, so check the resource before retrying them.

Next steps#