Errors

The API uses conventional HTTP status codes. Errors return a flat envelope:

{
  "error": "ApiError",
  "message": "You can only reply to messages from the last 30 days",
  "status": 400,
  "code": "reply_target_expired"
}

The code field is a stable, machine-readable identifier present on known error cases — branch on it rather than the human-readable message.

Status codes

Status	Meaning
400	Malformed request or validation failure.
401	Missing or invalid API key.
403	Authenticated but not allowed (plan/permission gate).
404	Resource not found.
409	Conflicting state (e.g. webhook limit reached).
429	Rate limit exceeded.

The API uses conventional HTTP status codes. Route handlers return a structured error envelope:

{
  "error": {
    "code": "invalid_content",
    "message": "content.text is required for text content",
    "details": { }
  }
}

The code field is a stable, machine-readable identifier — branch on it rather than the human-readable message.

Status codes

Status	Meaning
400	Malformed request.
401	Missing or invalid API key.
403	Authenticated but not allowed (plan/permission gate).
404	Resource not found.
409	Conflicting state (chat closed, channel not active, idempotency reuse).
422	Validation failed.
501	Endpoint is defined but not implemented yet.

Authentication failures (401/403) use a flatter shape: { "error", "message", "status" }.