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:

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.

Code
{
  "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

Error body shape

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

Code
{
  "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 an optional array of { field, message } objects, present on field-level validation errors. 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.