Reference

Errors

The API uses conventional HTTP status codes and a consistent JSON error body. Every error response includes a stable code string for programmatic handling, a human-readable message, and optional details.

Error response format

All errors follow this shape:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "content must be a string with at least 1 character",
    "details": {
      "field": "content",
      "reason": "too_short"
    }
  }
}

The details object is optional and may vary by error type. When present it provides additional context such as the offending field or validation constraint.

HTTP status codes
  • 200: success. The response body contains the requested resource or list.
  • 201: created. A new resource was created.
  • 204: no content. A delete or cancel succeeded.
  • 400: bad request. Validation error or malformed input.
  • 401: authentication failure. See authentication page for specific error codes.
  • 403: forbidden. The API key lacks the required scope or the workspace plan does not permit the operation.
  • 404: not found. The resource does not exist.
  • 409: conflict. An idempotency key mismatch or a state conflict (e.g. trying to publish a canceled post).
  • 429: rate limited. See rate limits page.
  • 500: internal server error. Contact support if this persists.
Error codes

Error codes are stable strings. Do not parse message text:

  • INVALID_REQUEST: request body failed validation.
  • AUTHENTICATION_REQUIRED: missing or empty Authorization header.
  • INVALID_API_KEY: unrecognized API key.
  • API_KEY_REVOKED: the API key was revoked.
  • API_KEY_EXPIRED: the API key has expired.
  • FORBIDDEN: insufficient scopes or plan limitations.
  • NOT_FOUND: the requested resource was not found.
  • CONFLICT: idempotency key conflict or invalid state transition.
  • RATE_LIMITED: request was throttled.
  • INTERNAL_ERROR: unexpected server error.