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:
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 itserror.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. 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 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.
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.
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} 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 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.
Retry reads with exponential backoff and jitter. For a mutation, reconcile first (see 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 anIdempotency-Key header. The Idempotency 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), or, when no response was stored, at least the created resource’s id (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.
Error details
A400 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:
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.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.
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.
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:
error keeps its string value. Beside it, every refusal also carries:
codeanddocUrl: the platform code for its HTTP status and that code’s section on this page;meta.requestId: the request id, which is also in theX-Request-Idheader.
INVALID_INPUT, or INVALID_REQUEST on the agent callback) also carries details:
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.
Retry guidance
When an operation mutates state, send an
Idempotency-Key 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). 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 andmeta.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.
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.MCP refused a call
Readerror.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.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.Reporting issues
When opening a support ticket or filing a bug, always include:- The
meta.requestIdfrom the failing response. - The HTTP method, path, and a redacted sample of the request body.
- The full
errorobject from the response body (code + message). - 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.
