Errors

Every non-2xx response from the Foil API returns a structured JSON envelope. Treat error.code as the stable, machine-readable field and error.message as human-facing guidance that may evolve.

Error envelope

{
  "error": {
    "code": "auth.missing_api_key",
    "message": "Missing Authorization header. Send Authorization: Bearer <token> to authenticate this request.",
    "status": 401,
    "retryable": false,
    "request_id": "req_0123456789abcdef0123456789abcdef",
    "docs_url": "https://usefoil.com/docs/api-reference/authentication",
    "details": {
      "next_action": "retry"
    }
  }
}

Field	Type	Meaning
`error.code`	string	Stable machine-readable code. Prefixed by category (`auth.`, `request.`, `rate_limit.`, `session.`, `gate.`, etc.). Branch on this.
`error.message`	string	Human-readable explanation. Safe to log; safe to surface to support or internal tooling. Do not pattern-match against it - it may change.
`error.status`	number	HTTP status code. Same as the response status.
`error.retryable`	boolean	Whether retrying the same request can reasonably succeed. `true` on 429 and 5xx; `false` on 4xx auth and validation failures.
`error.request_id`	string	Unique identifier for this request. Include it verbatim in any support correspondence.
`error.docs_url`	string, optional	When present, a deep-link to the most relevant docs section for this failure class.
`error.details`	object, optional	Category-specific data. See Details field below.

HTTP status codes

Status	When
`200`	Successful JSON response.
`201`	Resource created (management endpoints).
`204`	Successful, no response body (some DELETE operations).
`400`	Malformed JSON, malformed required headers, or protocol-level input that can’t be parsed.
`401`	Missing `Authorization` header.
`403`	API key is present but invalid, revoked, or not authorized for this endpoint / resource.
`404`	Resource not found, or not visible to the authenticated key.
`409`	Conflict - commonly a duplicate resource (e.g. creating an organization slug that already exists).
`422`	Validation failure - the request is well-formed but semantically invalid (e.g. required fields missing, values out of range).
`429`	Rate limit exceeded. Response includes `Retry-After` header.
`5xx`	Server error. Transient - safe to retry with exponential backoff.

4xx responses indicate the caller needs to change something before retrying; 5xx responses indicate Foil’s side needs to recover. The error.retryable field encodes this directly and is safe to key retry logic off.

Error code taxonomy

Error codes are namespaced with a category prefix. The prefix tells you which layer rejected the request; the suffix tells you specifically what went wrong.

Prefix	Meaning	Codes
`auth.*`	Authentication or authorization failure	`auth.missing_api_key`, `auth.invalid_api_key`, `auth.missing_bearer_token`, `auth.invalid_bearer_token`, `auth.secret_key_required`, `auth.secret_key_not_allowed`, `auth.insufficient_scope`, `auth.origin_not_allowed`, `auth.organization_inactive`, `auth.organization_access_denied`
`request.*`	The request was malformed, too large, not found, or failed validation	`request.validation_failed`, `request.not_found`, `request.invalid_json`, `request.invalid_content_type`, `request.payload_too_large`, `request.conflict`
`rate_limit.*`	Rate limit exceeded	`rate_limit.exceeded`
`billing.*`	Plan or quota limit reached	`billing.plan_limit_reached`
`session.*`	Collect and stored session state	`session.invalid_or_expired`, `session.invalid_state`, `session.nonce_consumed`, `session.sequence_mismatch`
`transport.*`	The client bundle or wire format is out of date	`transport.upgrade_required`, `transport.session_reset_required`
`gate.*`	Gate (agentic signup) errors	`gate.session_not_found`, `gate.session_expired`, `gate.session_already_resolved`, `gate.bot_detected`, `gate.validation_failed`, `gate.rate_limit`, `gate.delivery_consumed`
`internal.*`	Server-side failure; safe to retry	`internal.unavailable`

Branch your error handling on the category prefix first, the specific code second. A generic “auth failure” path that handles any auth.* code is usually correct, with specific codes adding nuance only where your UX demands it (e.g. handling auth.origin_not_allowed by reminding the developer to add their domain to the key’s allowed origins, or auth.insufficient_scope by pointing at the missing scope). The browser SDK surfaces its own client-side codes - config.* and runtime.*, plus transport.upgrade_required - documented alongside the SDK. See Browser SDK → Error codes for the full table, including retry semantics and the recommended fallback policy.

Details field

Some error codes include a structured details object with extra context.

Field errors (`request.validation_failed`)

{
  "error": {
    "code": "request.validation_failed",
    "message": "One or more fields failed validation.",
    "status": 422,
    "retryable": false,
    "request_id": "req_...",
    "details": {
      "fields": [
        {
          "name": "webhook_endpoint_id",
          "issue": "not_found",
          "expected": "active webhook endpoint subscribed to gate.session.approved",
          "received": "we_missing"
        }
      ]
    }
  }
}

Each fields[] entry carries:

name - dot-path to the offending field in the request body (or query)
issue - a stable short code describing why the value was rejected
expected - an optional human-readable description of what’s valid
received - the value the server saw (redacted for sensitive fields)

Next action hints

Some errors include a next_action in details to make retry logic straightforward:

`next_action`	What to do
`new_session`	The session is unrecoverable. Start a fresh Foil session on the client.
`reload_bundle`	The browser bundle is stale or unrecognized. Reload the page so a fresh `t.js` loads.

For everything else, key your retry logic off error.retryable and the HTTP status - see Retry strategy.

Enumerated fields

When a field only accepts a fixed set of values, the rejected field’s expected lists them.

{
  "error": {
    "code": "request.validation_failed",
    "message": "One or more fields failed validation.",
    "status": 422,
    "details": {
      "fields": [
        {
          "name": "status",
          "issue": "invalid_value",
          "expected": "active, suspended, or deleted",
          "received": "archived"
        }
      ]
    }
  }
}

Rate limiting

Rate-limited responses return 429 Too Many Requests with:

Retry-After header - seconds until the next acceptable retry
X-RateLimit-Limit - the ceiling for this organization and key type
X-RateLimit-Remaining - 0 at the point of rejection

Respect Retry-After. Don’t retry inside the window - further requests count against the limit and typically extend the cooldown. For bulk workflows, the server SDKs include built-in retry-with-backoff that honors this header. See Authentication → Rate limits for organization-level defaults.

Using `request_id`

Every response (success and failure) carries a request_id in the meta block for successful responses, and in error.request_id for failures. Include it verbatim when you:

Email security@usefoil.com about a suspected security issue
Open a support ticket about an unexpected error
Correlate a client-side report with server-side logs

The ID looks like req_0123456789abcdef0123456789abcdef (32 hex characters after the prefix). It’s unique per request and never reused.

Handling errors in the server SDKs

Each server SDK throws structured error types that mirror the envelope above. The Node SDK’s types illustrate the pattern every SDK follows.

Node.js

const {
  FoilApiError,
  FoilTokenVerificationError,
  FoilConfigurationError,
  safeVerifyFoilToken,
} = require("@abxy/foil-server");

try {
  const session = await client.sessions.get(sessionId);
} catch (err) {
  if (err instanceof FoilApiError) {
    console.error("API error", {
      code: err.code,
      status: err.status,
      requestId: err.request_id,
      fields: err.field_errors,
      docsUrl: err.docs_url,
    });

    if (err.status >= 500 || err.status === 429) {
      // Retry with backoff - use err.body.error.retryable in edge cases
    }
  } else if (err instanceof FoilConfigurationError) {
    // Deployment misconfiguration (missing secret, bad fetch) - fail loud
    throw err;
  }
}

// Token verification has its own exception, since it's a local op
const result = safeVerifyFoilToken(sealedToken, process.env.FOIL_SECRET_KEY);
if (!result.ok) {
  // result.error is a FoilTokenVerificationError
  return reject("invalid_foil_token");
}

Error classes across the SDKs:

SDK	Class names
Node.js	`FoilApiError`, `FoilTokenVerificationError`, `FoilConfigurationError`
Python	`FoilApiError`, `FoilTokenVerificationError`, `FoilConfigurationError`
Go	`APIError`, `TokenVerificationError`, `ConfigurationError`
Ruby	`Foil::Server::ApiError`, `Foil::Server::TokenVerificationError`, `Foil::Server::ConfigurationError`
PHP	`Foil\Server\ApiError`, `Foil\Server\TokenVerificationError`, `Foil\Server\ConfigurationError`

All expose equivalent fields - status, code, request_id, field_errors, docs_url, and the raw response body.

Retry strategy

A minimal retry loop that handles the common cases:

Read error.retryable. If false, don’t retry - the request will fail the same way every time.
If the status is 429, wait for Retry-After seconds before retrying.
If the status is 5xx, retry with exponential backoff (e.g. 0.5s, 1s, 2s, 4s, capped at 30s) with jitter.
Cap total retries at 3–5 attempts before surfacing the error to the caller.
Always log error.request_id on the last attempt so support can correlate.

The server SDKs ship with this logic built in - you generally only need to write your own for custom HTTP clients.

What’s next

Authentication

Key types, scopes, and lifecycle.

Pagination

Iterating through list endpoints.

API introduction

Surface-level summary of the API.

Troubleshooting

Operational guidance when things go wrong.

Get started

Detection

Gate

Webhooks

Management

Error envelope

HTTP status codes

Error code taxonomy

Details field

Field errors (`request.validation_failed`)

Next action hints

Enumerated fields

Rate limiting

Using `request_id`

Handling errors in the server SDKs

Retry strategy

What’s next

Authentication

Pagination

API introduction

Troubleshooting

​Error envelope

​HTTP status codes

​Error code taxonomy

​Details field

​Field errors (request.validation_failed)

​Next action hints

​Enumerated fields

​Rate limiting

​Using request_id

​Handling errors in the server SDKs

​Retry strategy

​What’s next

Authentication

Pagination

API introduction

Troubleshooting

Error envelope

HTTP status codes

Error code taxonomy

Details field

Field errors (`request.validation_failed`)

Next action hints

Enumerated fields

Rate limiting

Using `request_id`

Handling errors in the server SDKs

Retry strategy

What’s next