Error responses

Machine-readable routes on this domain return errors as RFC 9457 problem documents with the media type application/problem+json, never as an HTML error page. Alongside the standard type, title, status, detail and instance members, every response carries a stable code to branch on and a resolution array describing what to do next.

Branch on code or on type, not on title — the title is human-readable prose and may be reworded, while the other two are stable identifiers.

404 — Resource not found

Type URI
https://nirvanalabs.io/problems/not-found
Code
RESOURCE_NOT_FOUND
HTTP status
404

How to resolve

  • This is a real 404, not a transient failure — retrying the same path will not succeed.
  • Enumerate the valid paths from https://nirvanalabs.io/api/v1/pages or https://nirvanalabs.io/sitemap.xml instead of guessing.
  • For an agent-oriented index of the whole site, fetch https://nirvanalabs.io/llms.txt.

405 — Method not allowed

Type URI
https://nirvanalabs.io/problems/method-not-allowed
Code
METHOD_NOT_ALLOWED
HTTP status
405

How to resolve

  • This API is read-only. Reissue the request as GET or HEAD.
  • The Allow response header lists the methods this path accepts.
  • Writes happen against the product API, not this domain: https://docs.nirvanalabs.io/api/openapi.json

429 — Too many requests

Type URI
https://nirvanalabs.io/problems/rate-limited
Code
RATE_LIMITED
HTTP status
429

How to resolve

  • Wait for the interval given in the Retry-After header before retrying.
  • Read the RateLimit and RateLimit-Policy headers on every response to self-throttle before you are limited, rather than after.
  • Retry with exponential backoff and jitter; do not retry in a tight loop.

415 — Unsupported media type

Type URI
https://nirvanalabs.io/problems/unsupported-media-type
Code
UNSUPPORTED_MEDIA_TYPE
HTTP status
415

How to resolve

  • This endpoint serves application/json only.
  • Send Accept: application/json, or omit Accept entirely.

Requesting a machine-readable representation

Any page URL on this domain answers JSON or markdown instead of HTML when asked explicitly. Send Accept: application/json for a JSON descriptor of the page, or Accept: text/markdown for a markdown one. A wildcard Accept still returns HTML, so ordinary clients are unaffected.

To enumerate the site rather than guess at it, fetch /api/v1/pages, /sitemap.xml or /llms.txt.