Error Codes

All errors follow a consistent format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  },
  "meta": { "requestId": "req_a1b2c3d4e5f6a1b2" }
}

Authentication Errors (401)

Code	Description
`MISSING_TOKEN`	No `Authorization` header or missing `Bearer` prefix
`INVALID_TOKEN`	Token doesn't match any active token
`TOKEN_REVOKED`	Token has been explicitly revoked
`TOKEN_EXPIRED`	Token has passed its expiration date

Code	Description
`SCOPE_REQUIRED`	Token lacks the required scope for this endpoint
`FORBIDDEN`	Ownership check failed (trying to access another user's resource)
`PRO_REQUIRED`	Feature requires a Pro plan or higher
`BUSINESS_REQUIRED`	Feature requires a Business plan
`API_ACCESS_PRO_REQUIRED`	API access requires a Pro plan or higher
`IP_BLOCKED`	IP temporarily blocked due to repeated auth failures (edge worker, planned)

Code	Description
`BAD_REQUEST`	Malformed request body or missing required fields
`VALIDATION_ERROR`	Input validation failed (invalid URL, name too long, etc.)
`INVALID_JSON`	Request body is not valid JSON
`INVALID_REQUEST`	Required fields (`method`, `path`) missing from request

Code	Status	Description
`NOT_FOUND`	404	Resource doesn't exist or invalid ID format
`BOOKMARK_LIMIT_REACHED`	422	Plan bookmark limit reached (50,000 for Pro/Business)

Code	Description
`RATE_LIMITED`	Per-plan or per-endpoint rate limit exceeded

Check X-RateLimit-Reset header for when to retry. See Rate Limits for details.

Code	Description
`INTERNAL_ERROR`	Unexpected server error

If you consistently receive 500 errors, please contact support.