Errors and pagination

Common error shape

Many OpenDocs endpoints return JSON in this form:

{
  "error": "publish_failed",
  "message": "Workspace not found."
}

Some simpler failures return only:

{
  "error": "unauthorized"
}

Common error codes in the public API

Status	Example error	Meaning
400	invalid_request, publish_failed, update_failed	Validation or business rule failure
401	unauthorized	Missing or invalid auth
404	not_found	The target post does not exist for that user
429	rate_limited	Too many requests

Rate limits

Current server-side limits include:

• general API traffic: 120 requests per minute
• publish endpoint: 30 requests per minute

The JSON body for rate-limit responses looks like:

{
  "error": "rate_limited",
  "message": "Too many requests. Try again later."
}

Pagination shape

List endpoints return:

{
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "totalPages": 3
  }
}

Practical guidance

• Use modest limit values unless you truly need bigger pages.
• Prefer --json in the CLI when you want a script or agent to read pagination data.
• Use list before update when your automation needs to discover a postId.