Rate Limits and Errors

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:

When the limit is exceeded, the API returns 429 Too Many Requests. Back off until X-RateLimit-Reset has passed, then retry.

Code
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Try again in 42 seconds."
  }
}

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

HTTP status codes

Error body shape

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

Code
{
  "error": {
    "code": "validation_failed",
    "message": "content.default is required when no per-platform content is set",
    "field": "content.default"
  }
}

• code is a stable machine-readable identifier. Use this for branching logic.
• message is a human-readable explanation and may change between versions.
• field appears on validation errors and points at the offending request 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.