API Problem Types

Versioned API failures use RFC 9457 application/problem+json. The type URI identifies stable machine semantics; clients should branch on type or HTTP status, never parse the human detail.

index-not-found

HTTP 404. The requested identifier is not a published Mecone symbol or canonical slug.

resource-not-found

HTTP 404. The requested v1 path is not a public API resource.

commodity-not-found

HTTP 404. The requested identifier is not a published Mecone benchmark symbol or slug (raised by the /benchmarks routes and their legacy /commodities aliases).

venue-not-found

HTTP 404. The requested lake venue is not served by this API. An unknown venue and a deliberately excluded one produce the same response, so this problem is not evidence that the venue’s tape does not exist.

date-not-found

HTTP 404. The requested date is not a collected partition for this lake venue, or the venue has no collected days at all.

snapshot-not-found

HTTP 404. The requested lake snapshot time does not exist in the date partition, the partition holds no readable snapshot, or the stored object could not be read.

page-not-found

HTTP 404. The requested lake quotes page is past the last page at the requested page size.

method-not-allowed

HTTP 405. The resource exists but does not support the requested method. The response preserves the standard Allow header.

snapshot-too-large

HTTP 413. The lake snapshot is above the published byte ceiling and is refused rather than rendered. Whole-board objects are served from the lake’s bulk path, not from this API.

invalid-request

HTTP 422. A path, query, or body parameter failed validation. Raised by the public read routes and by the operator plane’s key-management requests alike.

unsupported-history-resolution

HTTP 400. The requested benchmark history range/resolution combination is not supported.

credential-invalid

HTTP 401. The presented API key is unknown, revoked, or expired. A presented key is strictly enforced and never falls back to anonymous access; requests that present no key are open anonymous testnet reads and never see this problem.

credential-scope

HTTP 403. The presented API key is valid but does not carry the scope this plane requires (for example lake:read for the /api/v1/lake routes).

benchmark-not-entitled

HTTP 403. The presented API key carries a per-index entitlement list and the requested benchmark or flagship index is not on it. Entitled slugs are fixed at issuance; contact Mecone to widen them.

rate-limited

HTTP 429. The presented API key is over its per-minute request limit. The response carries Retry-After, RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers; retry after the indicated delay.

index-unavailable

HTTP 503. The requested index cannot currently be served safely. Respect Retry-After when present.

official-round-unavailable

HTTP 503. No canonical API-committed round exists for the requested index. The API does not substitute a live/indicative snapshot.

distribution-unavailable

HTTP 503. A current source probability distribution is unavailable. This does not necessarily make an already committed scalar round unavailable.

statistics-unavailable

HTTP 503. Trailing index statistics are not available. Respect Retry-After when present.

daily-closes-unavailable

HTTP 503. Daily reference closes are not available. Respect Retry-After when present.

commodity-unavailable

HTTP 503. No usable observation for the requested benchmark is available at this time. Respect Retry-After when present.

lake-unavailable

HTTP 503. The prediction-market lake is not readable from this deployment, or could not be listed. Respect Retry-After when present.

normalizer-unavailable

HTTP 503. The lake quote normalizer is not installed in this deployment, so quote rows cannot be served.

request-failed

The request failed with the accompanying HTTP status without exposing internal implementation details.

response-invalid

HTTP 500. The service refused to serialize a response that did not satisfy its safety or finite-number requirements.

snapshot-unreadable

HTTP 500. The stored lake snapshot could not be decoded or normalized.

internal-error

HTTP 500. An unexpected server failure occurred. Supply the response’s X-Request-ID when contacting support.

Operator plane

The following problems appear only on the credential-administration plane under /api/admin/**, which is operated by the Mecone team. Public read integrations never see them. Malformed operator requests reuse the shared invalid-request problem (HTTP 422).

admin-unconfigured

HTTP 503. The admin allowlist or identity configuration is missing, so the operator plane fails closed.

admin-unavailable

HTTP 503. The identity provider could not be reached to verify the operator’s session. Respect Retry-After.

admin-unauthorized

HTTP 401. No valid operator session token was presented. API keys are consumer credentials, never operator identity, so an mck_ key is rejected here.

admin-forbidden

HTTP 403. The verified identity is not on the operator allowlist.

store-unavailable

HTTP 503. The credential store could not be reached. Respect Retry-After.

key-not-found

HTTP 404. No credential has the requested id.

key-already-revoked

HTTP 409. The credential is already revoked; it cannot be revoked again or rotated.