Errors and response handling

Canonical API errors are represented as problem documents. Use the HTTP status and stable code for program logic. title and detail are human-readable explanations and can change without changing the error's meaning. Execute the protected operation after a valid enforce-mode authorization and proof verification.

JSON

{
  "type": "about:blank",
  "title": "nonce reused",
  "status": 409,
  "detail": "The nonce was already used in this environment.",
  "code": "error.nonce_reused"
}

Authentication middleware, a reverse proxy, or a transport interruption may produce a response outside this JSON shape. Handle transport and parsing responses alongside API problem documents. The Node SDK raises GrayPassApiError for HTTP errors and also surfaces transport failures.

Validation responses

Canonical request-validation failures return HTTP 422 with application/problem+json and the Problem fields above. The stable code is error.context_invalid; detail identifies the invalid input. Correct the request before retrying. The downloadable OpenAPI and operation tables describe this response directly for generated clients.

Status classes

Status	Typical interpretation	Integration response
`400` or `422`	Malformed input or schema violation	Correct the request; do not blindly retry
`401`	Missing or invalid authentication	Obtain a valid credential through the correct authenticated path
`403`	Scope, caller, origin, audience, or environment restriction	Verify configuration and ownership; do not weaken checks
`404`	Object absent or not visible in the caller's boundary	Confirm the tenant, environment, and identifier
`409`	Request, lifecycle, idempotency, or concurrent-state conflict	Re-read state and follow the specific error code
`429`	Rate limit	Back off with jitter and preserve request identity
`5xx`	Service or dependency failure	Keep the operation unexecuted; retry only with safe idempotency

An authorization returning HTTP success may still contain challenge, hold, or deny. Conversely, the Express helper's HTTP responses are application responses and are not the same thing as raw authorization endpoint status codes. Distinguish transport success, policy decision, and business execution in your logs and metrics.

Actionable error families

Credential and isolation errors include error.browser_credential_not_allowed, error.environment_mismatch, error.caller_not_allowed, and error.not_found. Action configuration errors include error.action_not_registered, error.policy_inactive, error.context_invalid, and error.audience_not_allowed.

Request identity errors include error.request_stale, error.nonce_reused, error.idempotency_conflict, error.request_in_progress, and error.idempotency_stale. Lifecycle and proof errors include subject enrollment failures, challenge expiry or mismatch, unavailable signing, and inactive proof state. error.enforcement_not_approved means the requested enforcement configuration was rejected; preserve the existing mode and contact support with the environment and trace ID. error.commercial_access_unavailable requires resolution of the account's commercial access before using the requested live service; keep the protected operation unexecuted.

See the generated Reason codes for the contract vocabulary and Troubleshooting for corrective procedures. Verifier failure reasons are separately documented in Proofs.

Safe diagnostics

Record a timestamp, environment, operation, error code, and safe authorization or trace identifier. Do not record raw credentials, proofs, full action context containing sensitive material, or webhook secrets. If a response is ambiguous after consumption or a business side effect, consult the application's durable operation record before retrying execution.