Errors

Errors are returned as application/problem+json per RFC 9457, with a few Stripe-style extension members. Branch on the HTTP status and on code. Never branch on title or detail, which are written for humans and can change.

Format

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Request-Id: req_6f1c9a52-7b0e-4b7d-9c2e-0d3a8a1f5e44

{
  "type": "https://docs.appstrate.dev/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "detail": "name: Too small: expected string to have >=1 characters (+1 more)",
  "instance": "urn:appstrate:request:req_6f1c9a52-7b0e-4b7d-9c2e-0d3a8a1f5e44",
  "code": "validation_failed",
  "request_id": "req_6f1c9a52-7b0e-4b7d-9c2e-0d3a8a1f5e44",
  "errors": [
    {
      "field": "name",
      "code": "out_of_range",
      "message": "Too small: expected string to have >=1 characters"
    },
    {
      "field": "scopes",
      "code": "invalid_type",
      "message": "Invalid input: expected array, received string"
    }
  ]
}

Some errors carry additional members the client is expected to act on. For example, a run launch blocked by a missing connection returns the connections to choose from or to reconnect (candidate_connections, required_scopes, and similar) so a UI can resolve it without a second round trip. These members are documented on the operation that emits them.

Property names in problem documents are snake_case, like the rest of the wire format. A few identifiers keep their camelCase spelling (id, userId, createdAt, and similar); see the OpenAPI schemas.

Request ids

Every response, success or error, carries a Request-Id header of the form req_<uuid>. Quote it in support requests and log it on your side: the platform's logs and audit records carry the same id. If you send a valid W3C traceparent header, it is echoed back and the trace id is attached to the server logs for that request.

Validation errors

A request body that fails validation returns 400 with code: "validation_failed" and one errors[] entry per offending field, all in the same response. Bodies are strict: an unknown field is an error, not silently dropped, and a malformed JSON body is a 400 rather than a 500.

A missing field is required whatever its type, enum and union fields included. Three cases keep the code of the check that failed: a missing discriminator of a discriminated union (invalid_union), a field checked by a rule on the whole object (invalid_value), and a missing numeric field the schema coerces, such as size on POST /api/uploads (invalid_type).

Some operations put a field code of their own in errors[], such as invalid_input (a schedule's input), file_uri_in_prompt, no_tools_selected, scope_not_in_catalog and unrenderable_authorized_uri. Treat a field code you do not recognise like invalid_request.

field is a path: scopes, metadata.plan, or items[0].name for array elements.

A single bad query parameter or header is reported with code: "invalid_request" and a param instead of an errors[] array.

Type URIs

The type member is built from code: https://docs.appstrate.dev/errors/ followed by the code with every underscore replaced by a hyphen.

code:  validation_failed
type:  https://docs.appstrate.dev/errors/validation-failed

The URI identifies the error class. It is not a link you can rely on: docs.appstrate.dev does not serve it today. To find a code on this page, use its anchor: every row of the catalogues below carries code- followed by the code in lower case with hyphens (#code-validation-failed).

Lower-case before you look up

The substitution replaces underscores and nothing else. It does not lower-case, so the few upper-case codes produce a mixed-case URI:

code:  INVALID_URL
type:  https://docs.appstrate.dev/errors/INVALID-URL

Its row is #code-invalid-url: lower-case the last segment of the type, or the code with its underscores turned into hyphens.

Two catalogues

Two layers raise coded errors: the platform HTTP API (Error code catalog) and the AFPS runtime and CLI (AFPS runtime error codes). Only the API puts a type in a response; the runtime emits none. The runtime's rows take the anchor prefix code-afps-.

They are kept apart because the two catalogues collide. The API's integrity_mismatch (a version already published with different content) and the runtime's INTEGRITY_MISMATCH (stored bytes no longer matching their recorded hash) are unrelated failures. Under one anchor, one of the two readers would get the wrong explanation.

Error code catalog

These are the codes the platform HTTP API returns. The afps CLI and the embeddable runtime raise a separate set, catalogued under AFPS runtime error codes.

Four codes can come back from almost any endpoint: unauthorized, forbidden, internal_error and rate_limited. validation_failed, invalid_request and not_found cover most of the rest. Everything else is specific to a domain.

This list is maintained by hand and is not closed. It is checked against the code, but a release can add a code before this page lists it, optional modules (a billing module, for example) contribute codes of their own, and a self-hosted instance can load modules this page knows nothing about. Branch on status first and on code second, and treat a code you do not recognise as its status class rather than failing hard. Each operation in the OpenAPI document lists the responses it can return.

Codes marked billing module appear only when a billing module such as @appstrate/module-ee is loaded. Codes marked sidecar come from the /internal routes that the run sidecar calls, not from the public API.

Connection and readiness entries

A run blocked by its integrations answers 409 missing_integration_connection with one errors[] entry per integration (field: integrations.<id>). Each entry carries its own code and, where it helps a client act without parsing detail, extra snake_case members. On the credential proxy, a resolution failure comes back with its entry code as the top-level code of a 409 instead (for example must_choose_connection), with the entry in errors[]. In the chat, a model whose subscription credential died answers 409 needs_reconnection.

When the caller opted in to connect offers, an entry that an OAuth connect flow can clear also carries connect_url, expiresAt and packageId: a single-use, short-lived link to open, never to store.

AFPS runtime error codes

These come from @appstrate/afps-runtime, the portable bundle runner behind the standalone afps CLI. They are not platform API errors:

• Calling the HTTP API? You will not see them. The platform translates bundle failures at its boundary: DEPENDENCY_UNRESOLVED becomes dependency_unresolved, INTEGRITY_MISMATCH becomes bundle_integrity_mismatch, any other bundle code becomes bundle_invalid, and a signature policy failure becomes bundle_signature_invalid.
• Running the afps CLI, or embedding the runtime? These are the codes you will see. The runtime throws typed errors (BundleError, BundleSignaturePolicyError, ApiCallFailureError, ResolverError), each with a code, a message, and optional structured details. They are not problem documents and carry no type. The CLI prints a failure as message [CODE].

Bundle assembly

Raised by BundleError while reading, verifying or building a bundle.

Bundle validation

Reported by bundle validation, which afps verify prints as [CODE] path: message. The last two are warnings and do not make a bundle invalid.

Signatures and trust chains

Raised by BundleSignaturePolicyError under a required signature policy. Under warn, the same reasons are reported to a callback instead of thrown. These codes are lower case.

Outbound calls and resolvers

Raised when an integration's api_call tool is prepared or executed. ApiCallFailureError carries the lower-case codes the platform's credential proxy answers, with the same meaning; details holds the integration, the target as written and the declared allowlist. ResolverError carries the RESOLVER_ codes.

Retrying

• 429 or 503 with retry_after: wait that many seconds (the Retry-After header carries the same value), then retry. rate_limited, org_run_rate_limited, chat_capacity and shutting_down set it.
• 429 without it (org_run_concurrency_exceeded, upload_staging_limit_exceeded) and 503 starting: back off and retry once in-flight work has finished or the server is up.
• 5xx without a hint: retry with exponential backoff and jitter, starting around one second and capped at one minute. For a POST, send an Idempotency-Key so a retry cannot create a duplicate. Only the operations that declare the header accept it.
• 409 idempotency_in_progress: retry shortly with the same key. 422 idempotency_conflict: do not retry; that key belongs to a different request.
• Other 4xx: do not retry unchanged. The request, or the state it depends on, needs to change first. A few 409 codes (conflict, schedule_modified_concurrently, space_access_changed) ask you to reload the resource and try again.

Examples

Authentication failure

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json
WWW-Authenticate: Bearer error="invalid_token"

{
  "type": "https://docs.appstrate.dev/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or expired API key",
  "instance": "urn:appstrate:request:req_…",
  "code": "unauthorized",
  "request_id": "req_…"
}

Rate limited

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 42
RateLimit: limit=20, remaining=0, reset=42
RateLimit-Policy: 20;w=60

{
  "type": "https://docs.appstrate.dev/errors/rate-limited",
  "title": "Rate Limited",
  "status": 429,
  "detail": "Too many requests. Please try again shortly.",
  "instance": "urn:appstrate:request:req_…",
  "code": "rate_limited",
  "request_id": "req_…",
  "retry_after": 42
}

A header the credential cannot honor

{
  "type": "https://docs.appstrate.dev/errors/header-not-allowed",
  "title": "Header Not Allowed",
  "status": 400,
  "detail": "Appstrate-User is only supported with api_key auth, not session authentication.",
  "instance": "urn:appstrate:request:req_…",
  "code": "header_not_allowed",
  "request_id": "req_…",
  "param": "Appstrate-User"
}