Errors

The BenchKey API uses a single, consistent error envelope across every endpoint. When a request fails, the HTTP status is non-2xx and the body is always:

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_field",
    "message": "Field 'customer_id' is required.",
    "param": "customer_id",
    "request_id": "req_01J8X4abc123"
  }
}

Envelope fields

Field	Type	Description
type	string	Machine-stable error category (see Error types)
code	string	Specific machine-stable code within the type (see Error codes)
message	string	Human-readable description, safe to display to developers
param	string | null	The request field that caused the error, if applicable
details	object | null	Extra structured data (e.g. required_scope) when helpful
request_id	string	Echoes X-Request-Id — quote this when contacting support

Error types

The type field groups errors by category. Each type maps to a fixed HTTP status:

Type	HTTP status	Meaning
invalid_request_error	400 / 413	Malformed input, missing or invalid parameters, or body too large
authentication_error	401	API key is missing, malformed, or revoked
payment_required_error	402	Billing action required — plan doesn’t include API access, or tenant’s subscription is inactive
permission_error	403	Key exists but lacks the required scope or permission
not_found_error	404	Resource does not exist, or belongs to a different tenant
method_not_allowed_error	405	The HTTP method is not supported on this endpoint
request_timeout_error	408	The operation timed out — transient, safe to retry
conflict_error	409	Idempotency replay mismatch, duplicate resource, or in-progress conflict
gone_error	410	The resource existed but has been permanently removed
unsupported_media_type_error	415	Write request body sent without Content-Type: application/json
unprocessable_error	422	Input is structurally valid but violates a business rule
rate_limit_error	429	Per-key rate limit exceeded
api_error	500	Unexpected server-side failure
service_unavailable_error	503	A dependency is temporarily unavailable, or the tenant is suspended

Error codes

The code field is specific within a type. Use it for programmatic error handling — it is stable across API versions.

invalid_request_error (400 / 413)

Code	Description
missing_field	A required field was not supplied. param names the field.
invalid_field	A field was supplied but its value is invalid (wrong type, out-of-range, bad enum). param names the field.
invalid_query	A query parameter is invalid (wrong type, array where scalar expected, or out-of-range). param names the parameter.
invalid_idempotency_key	The Idempotency-Key header is present but does not meet length or character requirements.
invalid_value	A supplied value is semantically out of range for the target field (e.g. an integer exceeds the column’s 32-bit range, or a string exceeds its maximum length). Correct the value and retry. param names the field where known.
payload_too_large	The request body exceeds the maximum allowed size (HTTP 413).

authentication_error (401)

Code	Description
unauthorized	The Authorization header is absent, malformed, or contains a revoked key.

permission_error (403)

Code	Description
insufficient_scope	The key is valid but lacks the required scope. details.required_scope names the missing scope.
forbidden	The key is valid but is not permitted to perform this action for another reason.

payment_required_error (402)

Code	Description
upgrade_required	The key’s tenant plan does not include public API access. details contains required_plan, current_plan, and upgrade_url.
payment_required	A billing action is required to proceed (e.g. past-due balance or entitlement gate).
billing_subscription_required	The tenant’s billing subscription is inactive. API access is unavailable until billing is restored. details contains billing_required, reason, subscription_status, and current_period_end.

not_found_error (404)

Code	Description
not_found	The requested resource does not exist or does not belong to this tenant.

method_not_allowed_error (405)

Code	Description
method_not_allowed	The HTTP method used is not supported on this endpoint. The response includes an Allow header listing the accepted methods.

request_timeout_error (408)

Code	Description
request_timeout	The underlying operation timed out before completing. This is a transient error — retry with an Idempotency-Key to avoid duplicates. The response may include a Retry-After header.

conflict_error (409)

Code	Description
conflict	A duplicate or conflicting resource was detected.
idempotency_key_reuse	An Idempotency-Key was reused with a different request body or URL. See Idempotency.
idempotency_in_progress	A request with this Idempotency-Key is still being processed. Wait and retry.

gone_error (410)

Code	Description
gone	The resource existed but has been permanently removed and will not be restored. Stop retrying.

unsupported_media_type_error (415)

Code	Description
unsupported_media_type	The request body was not sent with Content-Type: application/json.

unprocessable_error (422)

Code	Description
unprocessable	The request is structurally valid but fails a business rule (e.g. closing a ticket that is already closed). The message field explains the specific rule.

rate_limit_error (429)

Code	Description
rate_limited	The per-key request limit was exceeded. The response includes a Retry-After header with the number of seconds to wait. See Rate limits.

api_error (500)

Code	Description
internal_error	An unexpected server-side error occurred. Quote the request_id when contacting support.

service_unavailable_error (503)

Code	Description
service_unavailable	A dependency (database, third-party service) is temporarily unavailable. Retry with exponential backoff.
tenant_suspended	The tenant account has been suspended. API access is unavailable until the account is reinstated.

Handling errors in code

curl

response=$(curl -s -w "\n%{http_code}" https://app.benchkey.com/api/v1/customers/cust_missing \
  -H "Authorization: Bearer $BENCHKEY_API_KEY" \
  -H "BenchKey-Version: 2026-06-13")

body=$(echo "$response" | head -n -1)
status=$(echo "$response" | tail -n 1)

echo "Status: $status"
echo "Body: $body"

Node.js

const res = await fetch(
  "https://app.benchkey.com/api/v1/customers/cust_missing",
  {
    headers: {
      Authorization: `Bearer ${process.env.BENCHKEY_API_KEY}`,
      "BenchKey-Version": "2026-06-13",
    },
  }
);

if (!res.ok) {
  const { error } = await res.json();
  // error.type, error.code, error.message, error.param, error.request_id
  if (error.code === "not_found") {
    console.error("Customer not found:", error.message);
  } else if (error.code === "rate_limited") {
    const retryAfter = res.headers.get("Retry-After");
    console.error(`Rate limited. Retry in ${retryAfter}s`);
  } else {
    console.error(`[${error.code}] ${error.message} (request_id: ${error.request_id})`);
  }
}

Example error response — missing required field

HTTP/1.1 400 Bad Request
Content-Type: application/json
X-Request-Id: req_01J8X4abc123

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_field",
    "message": "Field 'customer_id' is required.",
    "param": "customer_id",
    "request_id": "req_01J8X4abc123"
  }
}

Example error response — insufficient scope

HTTP/1.1 403 Forbidden
Content-Type: application/json
X-Request-Id: req_01J8X4def456

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key is missing the required scope 'tickets.write'.",
    "details": {
      "required_scope": "tickets.write"
    },
    "request_id": "req_01J8X4def456"
  }
}

What to log

At minimum, log error.code, error.message, and error.request_id for every non-2xx response. The request_id is the fastest path to support resolution when something goes wrong.