API Error Reference

When a request fails, the SocialRails API returns a JSON error response with an HTTP status code, an error code, and a human-readable message.

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "A human-readable description of the error."
  }
}

Error Codes

400 Bad Request

The request is malformed or missing required fields.

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Field \"content\" is required and must be a string."
  }
}

Common causes:

• Missing required fields in the request body
• Invalid JSON in the request body
• Content exceeds the 5,000 character limit
• Invalid platform name
• Invalid date format for scheduled_for
• Scheduling a post in the past

401 Unauthorized

The API key is missing, invalid, or expired.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid Authorization header. Use: Bearer sr_live_xxxxx"
  }
}

Common causes:

• No Authorization header in the request
• API key doesn't start with sr_live_
• API key has been revoked
• API key has expired

403 Forbidden

The API key doesn't have the required scope, or API access isn't available on the user's plan.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have write scope."
  }
}

Common causes:

• Trying to create a post with a read-only key
• Trying to use AI generation without the ai scope
• Using a key from a Free or Trial plan

404 Not Found

The requested resource doesn't exist or the endpoint is invalid.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Post not found."
  }
}

Common causes:

• Invalid post ID
• Post belongs to a different workspace
• Typo in the endpoint URL

413 Payload Too Large

The request body exceeds the 1MB size limit.

{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "Request body must be 1MB or smaller."
  }
}

429 Too Many Requests / Limit Exceeded

You've exceeded your plan's rate limit or a usage limit.

Rate limit exceeded:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Limit: 300 requests per hour."
  }
}

AI credit limit exceeded:

{
  "error": {
    "code": "LIMIT_EXCEEDED",
    "message": "Monthly AI credit limit reached (1000/1000 credits used). Upgrade your plan for more."
  }
}

For rate limits, check the X-RateLimit-Reset header and wait before retrying. For AI credit limits, usage resets at the start of each month. See Rate Limits for details.

500 Internal Server Error

An unexpected error occurred on our end.

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred."
  }
}

If you consistently receive 500 errors, please contact support. These errors are logged on our end and investigated.

Troubleshooting Checklist

1. Check your API key, Is it active and not expired?
2. Verify the Authorization header, Must be Bearer sr_live_... (note the space after Bearer)
3. Validate your request body, Use a JSON validator to check formatting
4. Check the endpoint URL, All endpoints start with /api/v1/
5. Review scopes, Does your key have the required scope for this operation?
6. Monitor rate limits, Check X-RateLimit-Remaining headers