Skip to main content
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:
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. 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.
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.

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 an Idempotency-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.
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:
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:
  • 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:
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.

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 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.

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

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.

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