Errors & rate limits

This page documents how the Doxbrix API reports errors and how rate limiting works, so your integration can handle failures gracefully and back off correctly.

Error format

Errors return a consistent JSON object with a machine-readable error code, a human-readable message, and (where relevant) the offending field:

{
  "error": "validation_error",
  "message": "The 'title' field is required.",
  "field": "title",
  "requestId": "req_01J8X9Z3K2M4N5"
}

Always log the requestId — include it when contacting support about a specific failed request.

HTTP status codes

Error codes

The error field is a stable string you can branch on:

Handling errors

Branch on the error code, not the message (messages may change):

try {
  await dx.pages.create({ title: '', spaceId: 'sp_01' })
} catch (e) {
  if (e.error === 'validation_error') {
    console.error(`Invalid field: ${e.field}`)
  } else if (e.error === 'rate_limited') {
    await sleep(e.retryAfter * 1000)
  } else {
    throw e
  }
}

Rate limits

API requests are rate-limited per API key. Limits depend on your plan:

Rate limit headers

Every response includes your current rate-limit state:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 583
X-RateLimit-Reset: 1700000000

When you hit the limit

A 429 response includes a Retry-After header (seconds) telling you when to retry:

{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Retry after 12 seconds.",
  "retryAfter": 12
}

Backing off

Implement exponential backoff with jitter on 429 and 5xx responses:

Idempotency and conflicts

For POST requests, an Idempotency-Key header lets you retry safely after a network error without creating duplicates. A 409 duplicate_slug means the resource already exists — fetch it rather than retrying blindly.

Next steps