Errors
Both surfaces share one error model. The table below is rendered from the ErrorCode
enum in the running service, so a code cannot be documented without existing and cannot
exist without being documented.
Errors arrive as RFC 9457 application/problem+json
with a machine-readable code, a human-readable detail, the request_id of the
failed call, and a retryable boolean. Dispatch on code; detail is for humans and
its wording is not part of the contract.
Absence is not in this table
Section titled “Absence is not in this table”not_found and unknown are not errors. They are envelope statuses returned with
HTTP 200, because “we looked and there is nothing” is an answer. A client that treats
absence as a failure will retry a question that has already been answered. See
Typed absence.
| Code | HTTP | Retryable | Caller action | Log level |
|---|---|---|---|---|
INVALID_IDENTIFIER |
400 | no | Fix the identifier; detail names the failed check |
info |
UNSUPPORTED_NAMESPACE |
400 | no | Use a supported namespace | info |
UNSUPPORTED_URI_FORM |
400 | no | Compressed/legacy Digital Link URIs are not supported | info |
MALFORMED_URI |
400 | no | Supply a syntactically valid URI | info |
NO_PRIMARY_IDENTIFIER |
400 | no | Supply an identifier that resolves to a subject | info |
INVALID_PARAMS |
400 | no | Correct the tool arguments; detail names the field |
info |
INVALID_FILTER |
400 | no | Correct the filter value | info |
UNSUPPORTED_FILTER |
400 | no | This facet is not backed by data at this revision | info |
INVALID_SORT |
400 | no | Use a supported sort key | info |
INVALID_CURSOR |
400 | no | Restart pagination; cursors are not durable | info |
BATCH_TOO_LARGE |
400 | no | Split the batch (max 1000) | info |
UNAUTHENTICATED |
401 | no | Present a valid API key | info |
INSUFFICIENT_SCOPE |
403 | no | The key lacks the required scope; mint one that has it | info |
TENANT_QUOTA_EXCEEDED |
402 | no | Upgrade the plan, or wait for the next period | warn |
RATE_LIMITED |
429 | yes | Back off; see the ratelimit-reset header |
info |
UNSUPPORTED_PROTOCOL_VERSION |
400 | no | Upgrade the MCP client | info |
INTERNAL_ERROR |
500 | yes | Retry; contact support with the request_id |
error |
17 codes, all of them reachable.