Skip to content

Error codes ​

Every Substrat surface answers a refusal as an RFC 9457 problem document, served as application/problem+json. The code it carries comes from one closed list, the same on every surface: a module never invents a code, it narrows one with a reason of its own. Each code has a page here, and the page's address is the type the document carries, so a refusal links to its own explanation.

json
{
  "type": "https://substrat.net/errors/permission-denied",
  "title": "Permission denied",
  "status": 403,
  "detail": "permission denied: customer:manage",
  "instance": "/api/op/customer/update",
  "error": "permission denied: customer:manage",
  "code": "permission_denied",
  "permission": "customer:manage"
}

The codes ​

codeStatusTitleMeans
unauthenticated401UnauthenticatedThe request carried no credential this surface accepts.
permission_denied403Permission deniedA permission check refused a caller the surface knows.
forbidden403ForbiddenA policy refused the request, whatever the caller's permissions.
not_found404Not foundThe addressed thing does not exist, or does not exist for this caller.
conflict409ConflictThe request is well formed, but the current state does not allow it.
validation_failed400Validation failedThe input did not parse, or broke a rule about its own values.
precondition_failed412Precondition failedA precondition the caller sent no longer holds.
rate_limited429Rate limitedThe caller is over a request budget.
unavailable503Service unavailableA fact about the deployment, not the request, stopped the answer.
internal500Internal errorThe platform failed, and the reason is not sent.

Switch on code, never on the status or the sentence. Two codes share 403, and detail is written for people.

The body ​

The members a problem may carry. A member with codes beside it appears only on those codes; the rest may appear on any problem.

  • type: The canonical identifier: https://substrat.net/errors/<code>, the page for that code. about:blank when the body names no code.
  • title: Short and human, and the same for every occurrence of a code. Do not parse it.
  • status: The HTTP status, repeated from the status line (RFC 9457 §3.1.2).
  • detail: What went wrong this time, as a sentence for a person. Never present on internal.
  • instance: The path of the request this answers, when the surface knows it.
  • error: A deprecated copy of detail, kept while older clients still read it. Read detail.
  • code: The taxonomy entry, one of the codes on this page. The member to switch on. Absent exactly when type is about:blank.
  • requestId: The id of the request that failed, the same as its x-substrat-request-id header. Quote it when reporting a failure.
  • permission (permission_denied): The permission key the check refused.
  • entity (permission_denied, precondition_failed): The record the refusal is about, as an entity reference ({ entityType, entityId }).
  • reason (forbidden, not_found, conflict, validation_failed, precondition_failed, rate_limited, unavailable): A slug the refusing module owns, narrowing the code. The platform's own are snake_case, but the wire does not enforce a grammar, so compare it as an opaque string. Branch on it; never show it.
  • errors (validation_failed): One entry per field that failed to parse: path, dotted into the input, and message.
  • retryAfter (rate_limited): Seconds to wait before retrying, the same value as the Retry-After header.
  • storeCode (unauthenticated, forbidden, not_found, conflict, validation_failed, precondition_failed, rate_limited, unavailable): The scope store's own error code, when the refusal came from a store. It is the store's vocabulary, not this taxonomy's.
  • storeBody (unauthenticated, forbidden, not_found, conflict, validation_failed, precondition_failed, rate_limited, unavailable): The scope store's own error body: only a refusal's (a 4xx), and only up to 1024 bytes of JSON.

A body with no code ​

When a surface has a status and nothing else, the body is RFC 9457's about:blank form. That happens when it relays a refusal raised somewhere else, or answers a throw nobody typed. The title is the status phrase and code is absent:

json
{
  "type": "about:blank",
  "title": "Bad request",
  "status": 400,
  "detail": "the shop is closed on Sundays",
  "instance": "/api/op/shop/checkout",
  "error": "the shop is closed on Sundays"
}

The absence is the answer, not an omission. A client switching on code falls through to its default branch instead of matching a code that would be a guess. Handle it by the status, and show detail.

Where this comes from ​

The codes, statuses, titles and members on these pages are read from @substrat-run/contracts (errors.ts), the same registry every surface renders its problems from, and CI fails if a page falls behind it. What a good API looks like explains why failures are part of the surface.