Errors

Every non-2xx response from the Tripwire 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://tripwirejs.com/docs/api-reference/authentication",
    "details": {
      "next_action": "retry"
    }
  }
}

Field	Type	Meaning
`error.code`	string	Stable machine-readable code. Prefixed by category (`auth.`, `rate.`, `validation.`, `session.`, `fingerprint.`, `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 Tripwire’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	Typical codes
`auth.*`	Authentication or authorization failure	`auth.missing_api_key`, `auth.invalid_api_key`, `auth.revoked_api_key`, `auth.origin_not_allowed`, `auth.environment_mismatch`
`rate.*`	Rate limit or quota	`rate.limited`, `rate.quota_exceeded`
`validation.*`	Input failed validation	`validation.invalid_field`, `validation.missing_field`, `validation.unsupported_value`
`session.*`	Durable session access	`session.not_found`, `session.expired`, `session.token_verification_failed`
`fingerprint.*`	Visitor fingerprint lookup	`fingerprint.not_found`, `fingerprint.expired`
`gate.*`	Gate-specific errors	`gate.service_not_found`, `gate.session_expired`, `gate.agent_token_invalid`, `gate.agent_token_revoked`
`collect.*`	Browser transport errors (usually surfaced to the SDK, not your backend)	`collect.attestation_failed`, `collect.chain_integrity_failed`, `collect.nonce_replay`

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. distinguishing auth.environment_mismatch for a helpful “did you mean to use a test key?” message).

Details field

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

Field errors (`validation.*`)

{
  "error": {
    "code": "validation.invalid_field",
    "message": "One or more fields failed validation.",
    "status": 422,
    "retryable": false,
    "request_id": "req_...",
    "details": {
      "fields": [
        {
          "name": "webhook_url",
          "issue": "must_be_https",
          "expected": "https://...",
          "received": "http://example.com/webhook"
        }
      ]
    }
  }
}

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
`retry`	Retry the same request, optionally with backoff.
`new_session`	The session is unrecoverable. Start a fresh Tripwire session on the client.
`reload_bundle`	The browser bundle is stale or unrecognized. Reload the page so a fresh `t.js` loads.
`contact_support`	The error is not recoverable from caller-side state. Open a support ticket with the `request_id`.

Allowed values

For enumerated fields, details.allowed_values tells you the full set.

{
  "error": {
    "code": "validation.unsupported_value",
    "message": "Unsupported value for field 'verdict'.",
    "status": 422,
    "details": {
      "header_name": null,
      "allowed_values": ["bot", "human", "inconclusive"]
    }
  }
}

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 key
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 per-key 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@tripwirejs.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 {
  TripwireApiError,
  TripwireTokenVerificationError,
  TripwireConfigurationError,
  safeVerifyTripwireToken,
} = require("@abxy/tripwire-server");

try {
  const session = await client.sessions.get(sessionId);
} catch (err) {
  if (err instanceof TripwireApiError) {
    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 TripwireConfigurationError) {
    // Deployment misconfiguration (missing secret, bad fetch) — fail loud
    throw err;
  }
}

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

Error classes across the SDKs:

SDK	Class names
Node.js	`TripwireApiError`, `TripwireTokenVerificationError`, `TripwireConfigurationError`
Python	`TripwireApiError`, `TripwireTokenVerificationError`, `TripwireConfigurationError`
Go	`APIError`, `TokenVerificationError`, `ConfigurationError`
Ruby	`Tripwire::Server::ApiError`, `Tripwire::Server::TokenVerificationError`, `Tripwire::Server::ConfigurationError`
PHP	`Tripwire\Server\ApiError`, `Tripwire\Server\TokenVerificationError`, `Tripwire\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

Management

Error envelope

HTTP status codes

Error code taxonomy

Details field

Field errors (`validation.*`)

Next action hints

Allowed values

Rate limiting

Using `request_id`

Handling errors in the server SDKs

Retry strategy

What’s next

Authentication

Pagination

API introduction

Troubleshooting

Get started

Detection

Gate

Management

​Error envelope

​HTTP status codes

​Error code taxonomy

​Details field

​Field errors (validation.*)

​Next action hints

​Allowed values

​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 (`validation.*`)

Next action hints

Allowed values

Rate limiting

Using `request_id`

Handling errors in the server SDKs

Retry strategy

What’s next