> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Platform API error codes: when each fires and how to handle it, plus troubleshooting by symptom for authentication, access, validation, conflicts, unknown writes and holds.

The Forge Platform API uses a small, stable set of error codes. The HTTP status is set on the response, and the same code appears in the JSON body's `error.code` field. Branch on `error.code`. `error.message` is a human-readable hint that may change between releases.

## Error envelope

Every error response shares this shape:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Agent with ID 'agent_abc123' does not exist.",
    "docUrl": "https://docs.gloo.com/forge/reference/errors#not_found"
  },
  "meta": {
    "requestId": "req_def456"
  }
}
```

| Field | Always present | Meaning |
| - | - | - |
| `error.code` | Yes | The machine-readable code. Branch on it. The codes are listed below. |
| `error.message` | Yes | A human-readable hint. It may change between releases, so never parse it. |
| `error.docUrl` | Yes | A link to this code's section on this page. It is stable for each code. |
| `error.reason` | No | A machine-readable sub-code, on the refusals that have one. See [Reasons](#reasons). |
| `error.details` | No | On a `400` or `422` validation refusal, one entry per failing field, each naming its `param`. See [Error details](#error-details). |
| `error.requiredPermission` | On every `403` | The permission the caller lacks (the code is then `permission_denied`), or `null` when no grant would change the answer. |
| `error.personRequired` | No | `true` when the caller's kind of credential can never hold the missing permission. |
| `error.decisionId` | On every `403` | The Trust Fabric decision the refusal recorded. [`GET /api/v3/me/denials/{decisionId}`](https://docs.gloo.com/forge/reference/http-api/actor/my-denials) explains it. |

New optional fields can be added to `error`; ignore fields you don't recognize.

Fresh JSON error responses carry the same server-generated correlation value in `meta.requestId` and the `X-Request-Id` header. Always preserve it when surfacing or reporting errors — it's the stable handle support uses to find the request in audit logs.

## Codes

Each code below is the target of its `error.docUrl`.

### `unauthorized`

**HTTP 401.** The bearer token is missing, malformed or expired, or it was signed by an unknown key. A request with no `Authorization: Bearer <key>` header says so in its message (`No API key was sent: …`); a key Forge cannot accept answers `Invalid or expired API key`. Every `401` carries the header `WWW-Authenticate: Bearer` (RFC 6750), naming the scheme to authenticate with.

Mint a fresh token through `POST /oauth/token`. If the failure persists, check that the External App's credentials haven't been rotated.

### `forbidden`

**HTTP 403.** The credential is valid, but the request is refused and no single grant would change the answer: a credential of the wrong kind (the caller already holds every permission the operation requires), or a refusal with `error.personRequired: true`, whose kind of credential can never hold the permission. `error.requiredPermission` is `null`, and `error.decisionId` names the recorded refusal. A `403` sent before the credential is authenticated names neither field. Explain it with `GET /api/v3/me/denials/{decisionId}`.

Call with the kind of credential the operation admits (its `x-forge-actor-kinds`), or, for `personRequired`, have a person act through a Personal key.

### `permission_denied`

**HTTP 403.** The credential is valid, but the key or app doesn't hold a permission the operation requires once its scopes narrow its role grants. `error.requiredPermission` is the first permission the operation requires that the caller lacks, and `error.decisionId` names the recorded refusal. Explain it with `GET /api/v3/me/denials/{decisionId}`.

Give the key or app a role that holds `error.requiredPermission` (Forge Console, `grants:manage`), or request a token with the scope that maps to it. See [Permissions and scopes](https://docs.gloo.com/forge/reference/conventions.md#permissions-and-scopes). Clients written before this code existed may branch on `forbidden` with a string `requiredPermission`; accept both.

### `resource_missing`

**HTTP 404.** The operation looked up the resource and it doesn't exist, or it exists but the caller's tenant can't see it.

Check the id. The 404-vs-403 distinction is intentional: a 404 reveals nothing about resources outside the caller's tenant. Clients written before this code existed may branch on `not_found`; accept both.

### `not_found`

**HTTP 404.** No route serves this path, under `/api/` or anywhere else on the Forge host (`/oauth/token`, `/.well-known/`, a webhook receiver). The answer is in this envelope. When another method serves that path, the answer is [`method_not_allowed`](#method_not_allowed) instead.

Check the path against the OpenAPI document.

### `method_not_allowed`

**HTTP 405.** The path is served, but not with this method. The `Allow` header names the methods it takes, sorted, and the message repeats them. This holds for `/api/v2`, `/api/v3`, any other path under `/api/` and every path outside it: `GET /oauth/token` answers `405` with `Allow: OPTIONS, POST`.

Check the method against the operation in the OpenAPI document, then send the request with one the `Allow` header names.

### `bad_request`

**HTTP 400.** Returned for:

* a malformed JSON body;
* a missing required field;
* a validation failure;
* any other client-side error the other codes don't cover.

Read `error.details`, when it is present, to find each failing field, plus `error.reason` when it is present, and fix the request. `error.message` summarizes the refusal.

### `unprocessable`

**HTTP 422.** The request is well formed, but Forge refuses one of its values. Examples: a workflow draft write that breaks a graph rule, run input that does not satisfy the workflow's input contract, a callback URL Forge will not deliver to, or an API Native rule such as a position whose role does not exist.

Read `error.message` and `error.details`, when present, for the value at fault, and change it. Sending the request again unchanged fails the same way. A `422` about an `Idempotency-Key` carries its own code, [`idempotency_key_reuse`](#idempotency_key_reuse).

### `payment_required`

**HTTP 402.** Metered spend is stopped: the budget that pays for this request is frozen or exhausted. Today `POST /api/v3/knowledge/ask` answers it before it retrieves anything or calls a model. The refusal carries `error.decisionId`; [`GET /api/v3/me/denials/{decisionId}`](https://docs.gloo.com/forge/reference/http-api/actor/my-denials) names the budget's reason, `budget_frozen` or `budget_exhausted`.

No grant fixes it. A person raises or unfreezes the budget in the Forge Console; then retry.

### `allowed_scopes_removed`

**HTTP 400.** An External App create or update sent `allowedScopes`. The field is read-only: an app's authority is its role grants.

Drop the field, and give or revoke the app's roles instead.

### `conflict`

**HTTP 409.** The request would break a uniqueness rule, or it raced another write. Examples: creating a duplicate, a write overtaken by another since it was read, or a preview that is no longer current.

Read the current state of the resource and adjust the request. Sending it again unchanged will fail the same way.

### `invalid_state`

**HTTP 409.** The resource's current state refuses the action. Examples: pausing a session that is not active, rotating the secret of a deactivated app or a revoked webhook, restarting a run that cannot restart, or deciding a recommendation already resolved.

Read the resource, and change its state first (or act on one in the right state). Sending the request again unchanged fails the same way.

### `gone`

**HTTP 410.** The resource existed and was removed for good. Example: `PATCH /api/v3/memory/{memoryId}` on a memory that was forgotten.

Stop using the id. Reading the resource may still answer it (a forgotten memory reads with `status: FORGOTTEN`), but it cannot be changed again.

### `payload_too_large`

**HTTP 413.** Either the request body is larger than the route accepts (for example a file upload over its limit), or the operation works over a set that has a fixed upper bound and the set is past it. A pod's owner history and a list that answers at most 500 rows are examples of such sets.

Send a smaller body, or narrow the request. Retrying it unchanged fails the same way.

### `rate_limited`

**HTTP 429.** The credential's [rate limit](https://docs.gloo.com/forge/reference/conventions.md#rate-limiting) is spent. The operation didn't run. The message names the class whose bucket is spent (`read`, `write` or `expensive`): the operation's `x-forge-rate-limit`.

Wait for the `Retry-After` header's number of seconds, then retry. A mutation may repeat under the same `Idempotency-Key`.

### `governance_door_stopped`

**HTTP 503.** An operator stopped the governance door this request passes through. The operation was refused before it had any effect, and no `Idempotency-Key` was spent.

Retry after a person reopens the door in the Console.

### `operator_stopped`

**HTTP 403.** An operator has stopped Forge. While it is stopped, a write, `knowledge/ask` and `knowledge/getChunks` are refused before they run, and no `Idempotency-Key` is claimed. The message is fixed ("Forge is stopped by an operator. A person resumes it in the Console."), and `error.decisionId` names the recorded refusal.

No grant fixes a stop: retry after a person resumes Forge in the Console. Reads keep working while Forge is stopped.

### `internal_error`

**HTTP 500**, sometimes 502 or 503. The server hit an unexpected error.

An error nothing in the route answered still arrives in this envelope, under `/api/v2` and `/api/v3`, with the message `Unexpected error` and the request's `meta.requestId`, which matches the `X-Request-Id` header. The message never carries the error's own text. Ingress webhooks under `/api/v2/ingress/` answer their own errors, in the same envelope, with constant messages.

A **503** `internal_error` with a `Retry-After` header is a transient runtime fault, such as a query that ran past its time limit, or one the runtime stopped because its database calls ran past their time limit, usually on an overloaded host. Its message is fixed: `Forge is briefly unavailable. Retry after the Retry-After delay.` Resend a read after the delay. A write is safe to resend with the same `Idempotency-Key`, because it never runs twice: once its key was claimed, the resend answers `409 idempotency_result_unavailable`, so check the resource and use a new key only if the write did not happen.

A refusal Forge could not record answers the same `503` with `Retry-After` and the message `Forge is unable to record this refusal. Please retry.` Nothing ran: resend after the delay.

A request whose rate limit Forge could not check answers the same `503` with `Retry-After` and the message `Forge's rate limiter is briefly unavailable, so the request did not run. Retry after the Retry-After delay.` The server could not complete the request: wait for `Retry-After`, then retry, and resend a write only with the same `Idempotency-Key`. The spec declares one `503` for both causes, and a transient fault can stop a request after its handler started. See [rate limiting](https://docs.gloo.com/forge/reference/conventions.md#rate-limiting).

Retry reads with exponential backoff and jitter. For a mutation, reconcile first (see [Retry guidance](#retry-guidance)). If the error persists, file a support ticket with `meta.requestId`.

## Idempotency codes

These five codes are returned only when a request carries an `Idempotency-Key` header. The [Idempotency](https://docs.gloo.com/forge/reference/idempotency.md) page has the full semantics: key format, scoping, replay and retention.

### `idempotency_key_invalid`

**HTTP 400.** The `Idempotency-Key` header is empty, is longer than 255 characters, or contains a byte outside printable ASCII (`0x21`-`0x7E`). An invalid key is rejected, never ignored, so a client is never left unprotected without knowing it.

Fix the key generator. A UUIDv4 string always fits the format.

### `idempotency_key_in_flight`

**HTTP 409.** An earlier request with the same credential, route and key is still running. Nothing ran twice.

Back off briefly, then retry the identical request.

### `idempotency_outcome_unknown`

**HTTP 409.** An earlier attempt with this key stopped without recording an outcome, so nobody knows whether it took effect. It was **not** retried.

This key can't be retried. Check the state of the resource you're authorized to read, or escalate. Use a new key only if a second effect is acceptable.

### `idempotency_key_reuse`

**HTTP 422.** The key was already used **on this same route** with a different query string or body. Nothing ran.

This is a client bug, so don't retry. Generate a new key for the new operation.

### `idempotency_result_unavailable`

**HTTP 409.** The request already completed, and its response can't be returned. The original request was **not** run again.

On an operation without a replay policy of its own, a same-key repeat returns the stored response ([Stored-response replay](https://docs.gloo.com/forge/reference/idempotency.md#stored-response-replay)), or, when no response was stored, at least the created resource's id ([Id-only replay](https://docs.gloo.com/forge/reference/idempotency.md#id-only-replay)). This code means neither can be returned. That happens when:

* the response was never stored (over 32 KiB, or carrying a one-time secret), or the operation decides access at the record's home or by who you are, and the response named no resource id;
* the request failed before producing a response;
* the operation's own replay policy withholds its response.

Don't automatically retry with a new key. Read the resource directly to reconcile the outcome first.

## Error details

A `400` whose body or query fails the operation's schema, and a `422` validation refusal, name every failing field in `error.details`, so a client can mark each one on its form without parsing `error.message`:

```json theme={null}
{
  "error": {
    "code": "bad_request",
    "message": "Invalid request body",
    "docUrl": "https://docs.gloo.com/forge/reference/errors#bad_request",
    "details": [
      { "path": "name", "param": "name", "message": "Expected string, received number", "code": "invalid_type" },
      { "path": "tags[2]", "param": "tags[2]", "message": "String must contain at least 1 character(s)", "code": "too_small" },
      { "path": "colour", "param": "colour", "message": "Unknown field: colour", "code": "unknown_field" }
    ]
  },
  "meta": { "requestId": "req_def456" }
}
```

| Field | Meaning |
| - | - |
| `path` | The failing field. Object keys are joined with dots and array indices are in brackets: `steps[0].name`. A query parameter is its name. `""` is the whole body. |
| `param` | The parameter the detail names: the same text as `path`. Every validation detail carries it. |
| `message` | A human-readable hint for that field. It may change between releases. |
| `code` | The machine-readable kind of failure, from the closed set below. Branch on it. |

A response carries at most 50 details. A body that fails before any field can be read, because it is not JSON or not an object, has one detail with path `""`.

The routes' own checks also answer details, including the shared list paging's `limit` and `cursor`: an unknown or repeated query parameter, a missing id, a cursor the route did not issue, or a filter outside its allowed values, such as `status=bogus`, names that parameter as its `path`, and a body that is not valid JSON answers one detail with an empty `path` and the code `invalid_json`. So does a refusal an operation maps from its own error: `reason must be at least 8 characters.` names `reason` with the code `too_small`, and a refusal about the whole request, such as a file upload's invalid `Content-Type` or `X-Filename` header, has an empty `path`. A refusal whose text comes from the record or write it is about, such as a workflow launch or draft-update conflict, an agent, policy or procedure write the store refuses, or a pod domain refusal, names its field only there, as does a workflow draft graph body its validator refuses. A knowledge record id the store cannot read names the id Convex refused, such as `sourceId`, with the code `invalid`, and an authored knowledge record body its validator refuses names the first field it refuses, such as `refs[0].externalId`; either has an empty `path` when the error names no field the request sent.

`error.details` is optional. Some checks that run after the schema, such as a value that must name a record the caller can see, still describe the field only in `error.message`. Branch on `error.code` first, and read `error.details` when it is present.

### Detail codes

The set is closed: a new code is listed here before any route sends it.

| `code` | Meaning |
| - | - |
| `required` | The field is missing. |
| `invalid_type` | The field has the wrong type, such as a number where a string belongs. |
| `invalid_value` | The field has the right type but is not one of the allowed values, such as an unknown enum member. |
| `invalid_format` | A string does not match its format, such as an email address, a URL or a date. |
| `too_small` | The value is shorter, smaller or has fewer items than the minimum. |
| `too_big` | The value is longer, larger or has more items than the maximum. |
| `unknown_field` | The body or the query names a field the operation does not accept. |
| `invalid_json` | The body, or a JSON-encoded parameter, is not valid JSON. |
| `invalid` | Any other rule failed, such as a check that relates two fields. |

### Details on the other surfaces

Every `/api/` route answers an error in the envelope above, with the request id in `meta.requestId` and the `X-Request-Id` header, except the procedure sandbox door (exception 2, below). That includes the webhook receivers, ingress and the email doors. The two vendor-compatible surfaces keep the vendor's error body, so the vendor's SDK still reads it, and add the envelope's fields to it: `error.code`, `error.docUrl` (the platform code for the status), and `meta.requestId`. `details` is added on a schema failure.

| Surface | Body |
| - | - |
| `/api/v2` and `/api/v3` | The envelope above. `/api/v3` answers with the same `/api/v2` handler, so the handler's details are the same. `/api/v3` refuses some requests before that handler: a body over the route's size limit is `413`; a path id that disagrees with the same field sent in the body or query is `400`, whose detail names the field you sent (such as `id`) and gives the path parameter in its message; and, on a route that puts its path id into the body, a body that is not valid JSON (detail code `invalid_json`) or is not a JSON object (`invalid_type`) is `400`, whose detail has an empty `path`. A handler's detail about an id the `/api/v3` path carries names the field the `/api/v2` route reads, such as `id`. |
| `/api/inference/v1/*`, and the coding-agent gateway on `/api/inference/openai/v1/*` | OpenAI's `{ "error": { "message", "type", "param", "code" } }`, plus `error.docUrl` and `meta.requestId`. `param` names the first failing field, as OpenAI's does, or is `null`; `code` is OpenAI's code, or the platform code when OpenAI's would be `null`. `details` sits inside `error`. An upstream error the gateway passes through gets the same fields. |
| The coding-agent gateway on `/api/inference/anthropic/v1/*` | Anthropic's `{ "type": "error", "error": { "type", "message" } }`, plus `error.code`, `error.docUrl` and `meta.requestId`, with `details` inside `error`. The id is also in the `request-id` header, where Anthropic's SDK reads it. |
| `/api/v1/proceduresApi/*` | Exception 2: the sandbox's flat `{ "error", "message" }`, with the other fields beside them. See [Procedure sandbox API errors](#procedure-sandbox-api-errors). |
| `/oauth/token` | Exception 1: [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749#section-5.2)'s `{ "error", "error_description" }`, with no added fields, because OAuth client libraries read exactly that shape. `/api/inference/v1/oauth/token` answers the same, and is deprecated: it sends `Deprecation` and `Link: </oauth/token>; rel="successor-version"`. Use `/oauth/token`. |

A `401` on the inference and gateway doors also sends `WWW-Authenticate: Bearer`.

## Reasons

`error.reason` refines `error.code` on the refusals that have a sub-code. The set is closed: a new reason is listed here before any route sends it.

| `error.reason` | With `error.code` | Sent by | Meaning |
| - | - | - | - |
| `requester_unavailable` | `forbidden` | `POST /api/v3/governance-requested-human-tasks` | This External App or key can no longer ask people. |
| `invalid_body` | `bad_request` | `POST /api/v3/governance-requested-human-tasks` | The request body is not a valid ask. |
| `form_invalid` | `bad_request` | `POST /api/v3/governance-requested-human-tasks` | The form definition is invalid. |
| `form_secret_like` | `bad_request` | `POST /api/v3/governance-requested-human-tasks` | The form asks for a password, a code or a key. |
| `eligibility_invalid` | `bad_request` | `POST /api/v3/governance-requested-human-tasks` | `eligibilityPermission` is not a catalog permission, or it is elevated. |
| `due_out_of_range` | `bad_request` | `POST /api/v3/governance-requested-human-tasks` | `dueInMs` is outside 15 minutes to 14 days. |
| `no_candidates` | `bad_request` | `POST /api/v3/governance-requested-human-tasks` | No one named can be asked. |
| `org_unit_required` | `bad_request` | `POST /api/v3/governance-requested-human-tasks` | The credential has no acting organization. |
| `requester_open_cap` | `conflict` | `POST /api/v3/governance-requested-human-tasks` | The requester has the most open asks allowed. |
| `person_open_cap` | `conflict` | `POST /api/v3/governance-requested-human-tasks` | The person asked already has the most open asks allowed. |
| `rate_limited` | `rate_limited` | `POST /api/v3/governance-requested-human-tasks` | Too many asks; retry after `Retry-After`. |
| `role_giving_refused` | `forbidden` | Role grant writes | The role-giving ceiling refused the change; `error.refusals` lists each refusal. |

## Procedure sandbox API errors

`/api/v1/proceduresApi/*` is the procedure sandbox's own door. It is not the Platform API, and it keeps an older, flat error shape:

```json theme={null}
{ "error": "CAPABILITY_DENIED", "message": "…", "decisionId": "…" }
```

`error` keeps its string value. Beside it, every refusal also carries:

* `code` and `docUrl`: the platform code for its HTTP status and that code's section on this page;
* `meta.requestId`: the request id, which is also in the `X-Request-Id` header.

A request the route itself refuses because a body field is missing or malformed (`INVALID_INPUT`, or `INVALID_REQUEST` on the agent callback) also carries [`details`](#error-details):

```json theme={null}
{
  "error": "INVALID_INPUT",
  "message": "Body field `capabilityDomain` must be a non-empty string",
  "details": [
    { "path": "capabilityDomain", "message": "Body field `capabilityDomain` must be a non-empty string", "code": "required" }
  ],
  "code": "bad_request",
  "docUrl": "https://docs.gloo.com/forge/reference/errors#bad_request",
  "meta": { "requestId": "req_def456" }
}
```

An `INVALID_INPUT` that a capability returns, rather than the route, describes the problem in `message` only.

The procedure SDKs that run inside a sandbox, for Node and for Python, read `error` as a string. A sandbox image pins its SDK version, so changing `error` to the object shape above would break procedures that are already deployed. That surface keeps its shape and only adds fields, and its codes are listed in the [procedures HTTP reference](https://docs.gloo.com/forge/reference/http-api/procedures).

## Retry guidance

| Status | Retryable? | Strategy |
| - | - | - |
| `401`, `403`, `404`, `409`, `410`, `422` | No (without changes) | These are deterministic outcomes. Retrying without changing the request will produce the same result. Re-auth or fix the request shape, then retry. |
| `400` | No (without changes) | `bad_request` errors are deterministic — fix the request shape. |
| `403 operator_stopped` | Not until a person acts | An operator stopped Forge. Retry after a person resumes it in the Console. |
| `402 payment_required` | Not until a person acts | The budget that pays for the request is frozen or exhausted. Retry after it is raised or unfrozen in the Console. |
| `429 Too Many Requests` | Yes | The credential's [rate limit](https://docs.gloo.com/forge/reference/conventions.md#rate-limiting) is spent: the error envelope with code `rate_limited`. Nothing ran. Honor the `Retry-After` header. If absent, back off exponentially starting at 1s with jitter. |
| `503 internal_error` with `Retry-After` | Reads: yes. Mutations: reconcile first. | A transient runtime fault. Wait the `Retry-After` delay, then resend a read. A write may have partly run, and under the same `Idempotency-Key` it is not run again, so reconcile as for any `5xx`. |
| `500-599` | Reads: usually. Mutations: reconcile first. | For reads, use bounded exponential backoff with jitter. For a mutation with an unknown or `5xx` outcome, preserve the original logical intent and retrieve authorized resource state or escalate before deciding whether another effect is appropriate. |
| `409 idempotency_key_in_flight` | Yes | The identical request is still running. Retry the identical request after a short delay to pick up its recorded response. |
| `409 idempotency_outcome_unknown` | No | An earlier attempt stopped mid-flight. Retrying under the same key will not execute anything. Reconcile authorized resource state or escalate; use a new key only if another effect is appropriate. |
| `409 idempotency_result_unavailable` · `422 idempotency_key_reuse` · `400 idempotency_key_invalid` | No | Retrying changes nothing. For `result_unavailable`, retain the completed claim and reconcile the resource before considering any new key. The one exception is a workflow dispatch whose result was withheld because the caller could not read the original run: once it can, a same-key repeat within 24 hours of the original dispatch returns that result ([Workflow dispatch replay](https://docs.gloo.com/forge/reference/idempotency.md#workflow-dispatch-replay)). After that window the same key dispatches again. Fix the client's key lifecycle for `key_reuse` or `key_invalid`. |

When an operation mutates state, send an [`Idempotency-Key`](https://docs.gloo.com/forge/reference/idempotency) with it and keep that key attached to the same logical intent. A completed claim prevents duplicate execution: a repeat under that key, including after a `5xx`, never executes the operation again, and returns the recorded result once the caller's permissions pass again ([Stored-response replay](https://docs.gloo.com/forge/reference/idempotency.md#stored-response-replay)). A possibly executed mutation is not permission to generate a new key and repeat the effect: retrieve authorized resource state or escalate before deciding that a new logical operation is safe. An `idempotency_result_unavailable` response has the same reconciliation requirement.

For direct HTTP reads, bounded retries on transport `429` and `5xx` responses are reasonable. Honor `Retry-After` on `429`; otherwise use exponential backoff with jitter. Transport and gateway failures can have non-JSON bodies, so preserve their status, headers, and raw diagnostic body. Mutation retries still follow the reconciliation rule above. A `429 rate_limited` is refused before the operation runs, so a mutation may repeat it under the same `Idempotency-Key`.

## Troubleshooting by symptom

Start with the narrowest evidence you have: the HTTP status and `meta.requestId`, the MCP refusal and its continuation, or the run ID and failed step. Preserve that evidence before you retry or change access.

### `401`: the credential did not authenticate

Check the origin, the `Authorization` header, token expiry, key revocation, client credentials and MCP sign-in. Re-mint an External App token when it has expired. Do not rotate unrelated credentials.

### `403`: the actor lacks effective authority

Read the required permission and the denial details. Then check the role, grant scope, credential scope, resource reach and runtime decision, in that order. Token scopes narrow roles; they never add one. See [Credentials and access](https://docs.gloo.com/forge/get-started/credentials-and-access.md).

### `400` or `422`: the request does not match the contract

Compare the method, path parameters, content type and JSON body with the generated operation page. Unknown fields are commonly rejected. Do not infer a body from a Console form.

### `404`: missing or intentionally hidden

The ID may be wrong, the record may be gone, or Forge may hide a resource the actor cannot read. List resources with the same credential and scope. An MCP refusal may include a continuation to the right list read.

### `409`: current state conflicts with the write

Re-read the resource and decide from its current version or lifecycle state. Do not blindly replay a stale update, approval, publication or ownership change.

### `429`, a budget refusal, or provider throttling

Honor `Retry-After` when present. Tell apart a Forge rate limit, a budget policy and an upstream provider limit; each has a different owner and recovery action.

### A write timed out or returned non-JSON

The outcome is unknown. Keep the original idempotency key, reconcile the target resource or run, and retry only when the operation contract and the observed state make that safe. See [Idempotency](https://docs.gloo.com/forge/reference/idempotency.md).

### MCP refused a call

Read `error.code`, `error.message`, the details and the optional `error.continuation`. A refusal can mean the tool is not listed for this connection, a read was sent to the write caller, confirmation is required, a person is required, or Forge refused the underlying operation. Do not bypass a confirmation by switching tools.

### A run is held

Inspect the pending approvals and human tasks, who is eligible to decide, the expiry, and the original actor's authority. A hold is not a failed retry. See [Approvals and HITL](https://docs.gloo.com/forge/run/approvals-and-hitl.md).

### A run failed

Open the failed node and the timeline, and capture the run ID, node ID, error, relevant request IDs, version and input classification. Work out whether an external effect may already have happened before you rerun. See [Observability](https://docs.gloo.com/forge/run/observability.md).

## Reporting issues

When opening a support ticket or filing a bug, always include:

1. The `meta.requestId` from the failing response.
2. The HTTP method, path, and a redacted sample of the request body.
3. The full `error` object from the response body (code + message).
4. The approximate timestamp (UTC) of the request.

`requestId` is the stable handle that lets the Forge team find the request in audit logs — without it, finding a specific failure in a high-volume deployment is significantly harder.

For a run or an MCP failure, also give the time range, environment, actor kind (never the secret), the run ID, the operation, the status or error code, the expected and observed results, and whether a write's outcome is unknown.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.