Errors & Status Codes

HTTP status codes we use

200, 201, 204 — success. 400 — validation error. 401 — not authenticated. 403 — not permitted. 404 — not found. 405 — method not allowed on this path. 409 — conflict. 428 — an Idempotency-Key header is required and was not sent. 429 — rate limited. 500 — server error. 503 — overloaded or restarting; retry with backoff.

REST error envelope

{
  "error": {
    "type": "not_found",
    "message": "…",
    "code": 404,
    "details": {}
  },
  "detail": "…"
}

error.type is one of a fixed set — not_found, permission_denied, validation_error, and others matching the status code. On a 500, the envelope also carries error.incident_id — quote the incident id when you contact support.

PRISM envelope

Every MCP tool call and every entity_crud-family invocation returns this shape. Success:

{
  "success": true,
  "data": {},
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_items": 0,
    "total_pages": 0,
    "has_next": false,
    "has_prev": false
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

Error:

{
  "success": false,
  "error": { "code": "…", "message": "…", "details": {}, "hint": "…" },
  "meta": { "request_id": "…", "timestamp": "…" }
}

meta.request_id is minted fresh on every response. It's what the SDKs expose as request_id (Python) and requestId (TypeScript) — include it when you report a problem.

MCP and OAuth error catalog

MCP-door and OAuth errors carry a richer, self-describing envelope:

{
  "error": {
    "code": "…",
    "http_status": 0,
    "message": "…",
    "remediation_hint": "…",
    "docs_url": "…",
    "request_id": "…",
    "details": {}
  }
}

A 429 also carries Retry-After. Every code below links to its own page with the exact HTTP status, message, and remediation hint.

SDK exception mapping

The Python SDK raises typed exceptions: PermissionDenied, NotFound, ValidationError, RateLimit (carries retry_after), ServerError, AuthenticationError, InvalidOperation.

The TypeScript SDK raises the equivalent set: AuthenticationError, PermissionDeniedError, NotFoundError, ValidationError, RateLimitError (carries retryAfter), ServerError, DevApiError, McpApiError.

Catch the typed exception rather than pattern-matching the message string — the shape is part of the SDK's stable contract.

Error code catalog

Every code the MCP and OAuth surfaces can return, with the status it carries. Each links to its own page with the remediation and the envelope filled in.

Code	HTTP	Meaning
`CODE_ALREADY_USED`	400	The authorization code has already been redeemed.
`CODE_EXPIRED`	400	The authorization code has expired.
`INVALID_GRANT`	400	The provided authorization grant or refresh token is invalid, expired, revoked, or does not match the redirect URI used in the authorization request.
`INVALID_REQUEST`	400	The request is missing a required parameter, includes an invalid parameter value, or is otherwise malformed.
`INVALID_SCOPE`	400	The requested scope is invalid, unknown, malformed, or exceeds what the client is authorized to request.
`PKCE_REQUIRED`	400	PKCE (code_challenge and code_challenge_method) is required for this authorization request.
`PKCE_VERIFICATION_FAILED`	400	The code_verifier does not match the code_challenge provided during authorization.
`REDIRECT_URI_MISMATCH`	400	The redirect_uri in this request does not match any URI registered for this client.
`UNSUPPORTED_GRANT_TYPE`	400	The authorization server does not support the requested grant type.
`UNSUPPORTED_RESPONSE_TYPE`	400	The authorization server does not support the requested response type.
`INVALID_CLIENT`	401	Client authentication failed (unknown client, no client authentication included, or unsupported authentication method).
`TOKEN_EXPIRED`	401	Bearer token is past its expiration time.
`TOKEN_INVALID`	401	Bearer token is invalid, malformed, or revoked.
`ACCESS_DENIED`	403	The resource owner or authorization server denied the request.
`CLIENT_INACTIVE`	403	The OAuth client is disabled or has been deactivated.
`INSUFFICIENT_PERMISSIONS`	403	Caller is authenticated but lacks permission for this resource.
`INSUFFICIENT_SCOPE`	403	Token does not have the required scope for this operation.
`TENANT_SUSPENDED`	403	The tenant for this request has been suspended.
`ORGANIZATION_NOT_FOUND`	404	The organization referenced by this request does not exist or is not accessible.
`RESOURCE_NOT_FOUND`	404	The requested resource does not exist or is not accessible to this caller.
`RATE_LIMITED_DAILY`	429	Daily request quota exceeded for this client.
`RATE_LIMITED_PER_HOUR`	429	Per-hour rate limit exceeded for this client.
`RATE_LIMITED_PER_MINUTE`	429	Per-minute rate limit exceeded for this client.
`INTERNAL_ERROR`	500	An unexpected error occurred while processing the request.
`SERVER_ERROR`	500	The authorization server encountered an unexpected condition.
`TEMPORARILY_UNAVAILABLE`	503	The service is temporarily unable to handle the request due to maintenance or overload.