Error Codes

All errors follow a consistent format:

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

Errors raised by the API gateway before your request reaches the API (rate limiting, IP blocking, malformed framing, oversized bodies, unknown paths) use the same envelope with a plain-string error message:

{
  "error": "Rate limit exceeded",
  "meta": { "requestId": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" }
}

meta.requestId is present on every error, gateway or API. The gateway mints a UUID per request and forwards it to the API, which echoes it, so a single id identifies the request end to end — quote it when contacting support.

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

Authorization Errors (403)

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 paid plan (Pro)
`BUSINESS_REQUIRED`	Feature requires a Business plan
`API_ACCESS_PRO_REQUIRED`	API access requires a paid plan (Pro)

Validation Errors (400)

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

Resource Errors (404, 409, 422)

Code	Status	Description
`NOT_FOUND`	404	Resource doesn't exist or invalid ID format
`BOOKMARK_LIMIT_REACHED`	422	Plan bookmark limit reached (50,000 on Pro)
`COLLECTION_TOO_LARGE`	422	Collection trash or restore would move more than 1,000 collections and bookmarks (trashed bookmarks included); nothing was changed. See collections for the fix
`INVALID_FILE_TYPE`	422	Uploaded file is not an accepted image type (JPEG, PNG, GIF, WebP)
`FILE_TOO_LARGE`	422	Uploaded file exceeds the 10 MB per-file limit
`STORAGE_LIMIT_REACHED`	422	Total storage quota (500 MB) exceeded
`RESERVATION_INVALID`	400	Upload reservation is expired, already used, or doesn't match the bookmark

Rate Limiting (429)

Code	Description
`RATE_LIMITED`	Per-plan or per-endpoint rate limit exceeded
`TOO_MANY_PENDING_UPLOADS`	Too many outstanding upload reservations (max 5)

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

Server Errors (500)

Code	Description
`INTERNAL_ERROR`	Unexpected server error

If you consistently receive 500 errors, please contact support.

Planned Error Codes

The following error codes are planned for future releases and are not yet active:

Code	Description
`IP_BLOCKED`	IP temporarily blocked due to repeated auth failures (edge worker)