Errors, status codes, and pagination

Status codes

• 200 — Success.
• 201 — (not used today) reserved for future creations.
• 400 — Bad request (missing fields, invalid query values). Shape: { error: string, issues?: zodIssue[] }.
• 401 — Unauthorized when the Bearer token is missing or invalid.
• 404 — Resource not found or does not belong to the caller.
• 422 — Validation failed for Posts payloads (Zod issues included).
• 429 — Rate limited; honor the Retry-After header when present.
• 500 — Unexpected server error.

issues matches Zod’s format (path, message, code).

Pagination

All list endpoints (/media, /posts, /social-accounts, /post-results) accept offset-based pagination.

Query parameters

• offset — number, default 0, must be ≥ 0.
• limit — number, default 10, max 100.

Response envelope

{
  "data": [/* items */],
  "meta": {
    "offset": 0,
    "limit": 10,
    "total": 123
  }
}

total represents the total rows visible to the current workspace after all filters are applied.