Copy page

Get started

API rate limits and error codes

Rate limits

OmniSocials enforces a per-API-key rate limit of 100 requests per minute on every endpoint. Limits reset on a rolling 60 second window.

Every response includes three headers describing your current budget:

Header	Meaning
X-RateLimit-Limit	The ceiling for this key. Currently 100.
X-RateLimit-Remaining	Requests left in the current window.
X-RateLimit-Reset	Unix timestamp when the window resets.

When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header (seconds) and a retry_after value in the body. Back off for that long, then retry.

JSON
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 42 seconds."
  },
  "retry_after": 42
}

Rate limits are enforced per key, not per workspace. Splitting heavy workloads across multiple keys is a valid scaling strategy.

HTTP status codes

Status	Meaning
200	Success
201	Resource created
204	Success with no body (typically deletions)
400	Validation error. See error.details for the field(s) that failed.
401	Missing or invalid API key
402	Insufficient credits (e.g. x_credits_insufficient on an X link post; error.details carries credits_required, credits_balance, and credits_reserved)
403	Valid key, but missing the scope required for this endpoint
404	Resource not found
409	Conflict: the media item is still used by a post (media_in_use), the same inbox reply was already sent (duplicate_reply), an automation already covers the post, or an X automation cannot turn on while X DMs are off (x_dms_off). Publishing a post that is already published returns 400 with already_published
429	Rate limit exceeded
500	Internal error. Retry with exponential backoff.
503	Temporary outage or scheduled maintenance. On media uploads: storage_unavailable, see below.

Storage outages

When our storage provider is down, an upload cannot be stored. Every route that stores media then returns 503 with the code storage_unavailable, a Retry-After header (seconds), and the same value as retry_after in the body:

JSON
{
  "error": {
    "code": "storage_unavailable",
    "message": "Our storage provider is temporarily unavailable. Your file was not stored. Try again in a few minutes."
  },
  "retry_after": 30
}

This applies to POST /media/upload, /media/upload-from-base64, /media/upload-from-url, the presigned upload URL, and media_urls on post create and update. Nothing is wrong with your request and nothing was stored: no media item and no post. Wait for Retry-After, then send the same request again. A presigned upload URL stays valid for the retry until it expires.

Error body shape

Every 4xx and 5xx response follows the same shape:

JSON
{
  "error": {
    "code": "validation_error",
    "message": "content.default is required when no per-platform content is set",
    "details": [
      { "field": "content.default", "message": "content.default is required" }
    ]
  }
}

• code is a stable machine-readable identifier. Use this for branching logic. Field-level validation uses validation_error.
• message is a human-readable explanation and may change between versions.
• details is optional and code-specific. On field-level validation errors it is an array of { field, message } objects; other codes attach their own shapes (for example, x_credits_insufficient carries credit balances, and media-limit errors carry per-platform file details). There is no top-level error.field.

Retry strategy

Retry 429, 500, 502, 503, and 504 with exponential backoff. Do not retry 400, 401, 403, 404, or 409 without first fixing the underlying request.

A reasonable default is three attempts with delays of 1s, 2s, and 4s. Cap total wait time at 30 seconds.