The Socialit API uses conventional HTTP status codes and returns JSON error bodies.

Status codes

Error body

Most errors return an error string:

{ "error": "NotFound" }

Validation errors

Validation failures include a Zod-style issues array describing each problem:

{
  "error": "ValidationError",
  "issues": [
    {
      "code": "too_small",
      "minimum": 1,
      "path": ["content"],
      "message": "String must contain at least 1 character(s)"
    }
  ]
}

Insufficient credits

Publishing returns 402 with the required and available credit amounts:

{
  "error": "InsufficientCredits",
  "required": 3,
  "available": 1,
  "breakdown": []
}

Cross-workspace access

For security, requesting a resource that exists but belongs to another workspace returns 404 NotFound (rather than 403), so the existence of other workspaces’ resources is never revealed.