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.
{
"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
code | Status | Title | Means |
|---|---|---|---|
unauthenticated | 401 | Unauthenticated | The request carried no credential this surface accepts. |
permission_denied | 403 | Permission denied | A permission check refused a caller the surface knows. |
forbidden | 403 | Forbidden | A policy refused the request, whatever the caller's permissions. |
not_found | 404 | Not found | The addressed thing does not exist, or does not exist for this caller. |
conflict | 409 | Conflict | The request is well formed, but the current state does not allow it. |
validation_failed | 400 | Validation failed | The input did not parse, or broke a rule about its own values. |
precondition_failed | 412 | Precondition failed | A precondition the caller sent no longer holds. |
rate_limited | 429 | Rate limited | The caller is over a request budget. |
unavailable | 503 | Service unavailable | A fact about the deployment, not the request, stopped the answer. |
internal | 500 | Internal error | The 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:blankwhen 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 oninternal.instance: The path of the request this answers, when the surface knows it.error: A deprecated copy ofdetail, kept while older clients still read it. Readdetail.code: The taxonomy entry, one of the codes on this page. The member toswitchon. Absent exactly whentypeisabout:blank.requestId: The id of the request that failed, the same as itsx-substrat-request-idheader. 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, andmessage.retryAfter(rate_limited): Seconds to wait before retrying, the same value as theRetry-Afterheader.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 (a4xx), 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:
{
"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.