Errors and limits

Errors

Error envelopes vary by endpoint. Organization authorization failures can use a string error with a top-level code:

{
  "error": "Insufficient scope",
  "code": "insufficient_scope",
  "requiredScopes": ["servers:read"]
}

Shared route errors can use a nested object:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid Authorization header"
  }
}

Storage errors can also include errorCode, message, and remediation. npm registry errors use { "error": "unauthorized" } or { "error": "not found" }. Use the HTTP status first, then the documented endpoint-specific code.

Rate limits

Throttled responses include Retry-After. Some auth responses also expose X-RateLimit-Remaining and X-RateLimit-Reset. There is no single universal request quota across this reference. The npm read registry does not apply a per-IP request limit.

Retry behavior

Cache and reuse an unexpired exchanged JWT to avoid unnecessary exchange calls. Retry read requests after transient failures with bounded backoff. Before retrying a mutation, inspect its resource and jobs; most infrastructure endpoints do not provide an idempotency-key contract.

Invitation creation requires Idempotency-Key. Reuse that key only with the same body. A changed body returns a conflict, and terminal replay omits the capability URL.

During application maintenance, affected API requests return 503 with code: "MAINTENANCE_MODE", Retry-After: 60, and Cache-Control: no-store.