Skip to content

forbidden ​

A policy refused the request, whatever the caller's permissions.

StatusTitletype
403Forbiddenhttps://substrat.net/errors/forbidden

403 is also the status of permission_denied, so switch on code, not on the status.

What it means ​

A rule of the platform or of the surface refused the request. The caller's roles did not: granting them more would not change the answer. reason, when present, names the rule. A refusal by a permission key is permission_denied, the other 403.

When it is returned ​

  • A deploy or push the platform refuses.
  • A sandbox rule: a preview scope asking for an outbound effect, a caller that could not prove what it is, a capability the caller does not hold.
  • A platform-internal route reached by a caller it does not serve.

What it carries ​

  • reason: 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.

Relayed from a scope store, it may also carry storeCode and storeBody. See the body for the members any problem may carry.

What to do ​

Do not retry unchanged, and do not ask for a role. Read detail and reason for the rule, and change what the request asks for. If the rule should not apply to you, raise it with support and quote requestId.

In /openapi.json ​

Documented on every operation's failure responses.

Every error code