Error Reference

All Relayer API errors follow a consistent response envelope. This page covers the error format, HTTP status codes, common business errors, and how to handle them.

Error response format

Every error response uses the same envelope as successful responses, with success: false:

{
  "success": false,
  "message": "Validation failed: amount must be positive",
  "statusCode": 400,
  "timestamp": "2026-05-15T12:00:00.000Z",
  "path": "/v1/payout/accounts/quote"
}

Field	Type	Description
`success`	`boolean`	Always `false` for errors
`message`	`string`	Human-readable error description
`statusCode`	`number`	HTTP status code (mirrors the response status)
`timestamp`	`string`	ISO 8601 timestamp of when the error occurred
`path`	`string`	The request path that returned the error

Some agent endpoints add structured error codes inside the body for client-side dispatch — see Agent-specific errors below.

HTTP status codes

4xx — client errors

Status	Name	Meaning
`400`	Bad Request	Request body or query parameters are invalid or missing required fields
`401`	Unauthorized	API key / JWT / HMAC is missing, malformed, expired, or invalid
`402`	Payment Required	An x402-gated resource requires a USDC payment (Agent Kit only)
`403`	Forbidden	Caller is authenticated but lacks scope or permissions for this endpoint
`404`	Not Found	The requested resource does not exist (wrong ID, deleted, or wrong path)
`409`	Conflict	Operation conflicts with existing state (e.g., duplicate resource)
`422`	Unprocessable Entity	Request is well-formed but fails business validation (e.g., insufficient balance)
`429`	Too Many Requests	Rate limit exceeded — back off and retry

5xx — server errors

Status	Name	Meaning
`500`	Internal Server Error	Unexpected server-side error — contact support if persistent
`502`	Bad Gateway	An upstream service returned an error
`503`	Service Unavailable	API is temporarily unavailable — retry with exponential backoff

2xx with caveats

Status	Meaning
`202 Accepted`	Returned by signing endpoints when the action is queued for human approval. Body contains `{ approvalId }`. Poll `/v1/signing/approvals/{id}` until resolved

Authentication errors

Missing key
Invalid key
Insufficient scope

{
  "success": false,
  "message": "Authorization header is missing",
  "statusCode": 401,
  "timestamp": "2026-05-15T12:00:00.000Z",
  "path": "/v1/signing/wallets"
}

Fix: Add the Authorization: ApiKey rk_... header to your request.

{
  "success": false,
  "message": "API key not found",
  "statusCode": 404,
  "timestamp": "2026-05-15T12:00:00.000Z",
  "path": "/v1/signing/wallets"
}

Fix: Verify your API key is correct and was not revoked. Sandbox keys don’t work in production — and vice versa.

{
  "success": false,
  "message": "Insufficient permissions for this resource",
  "statusCode": 403,
  "timestamp": "2026-05-15T12:00:00.000Z",
  "path": "/v1/signing/wallets"
}

Fix: Your API key’s scope (e.g. integrator:read) does not cover this endpoint. Generate a new key with the right scope, or check whether the endpoint is dashboard-only (in which case it’s not callable from external integrations).

Agent-specific errors

Agent endpoints use structured error codes inside the body so the SDK can dispatch programmatically:

`error` code	HTTP	Cause
`invalid_auth`	401	Missing HMAC headers, agent not found, or signature mismatch
`expired_timestamp`	401	`x-request-timestamp` drift exceeds ±60 seconds
`agent_killed`	401	Agent status is `killed` — re-provision before retrying
`budget_exhausted`	402 / 403	One or more budget layers exhausted. Response includes `failedLayers: ["infra" \| "tokens" \| "payments"]`
`kill_switch_active`	503	Global kill switch tripped — payments blocked (fail-safe)
`x402_payment_required`	402	The downstream x402 resource requires payment — handled by `x402fetch`
`approval_required`	202	Payment exceeds approval threshold — body contains `approvalId` to poll

Validation errors

400 responses include the specific field and constraint that failed in message:

{
  "success": false,
  "message": "Validation failed: amount must be a positive number",
  "statusCode": 400,
  "timestamp": "2026-05-15T12:00:00.000Z",
  "path": "/v1/payout/accounts/quote"
}

For requests with multiple validation failures, message typically lists the first offending field. Check your request payload against the schema in the API Reference.

Common business errors

422 Unprocessable Entity is returned when a request is well-formed but conflicts with business rules:

`message` (representative)	Kit	Cause
`Quote has expired`	Payout	The quote’s validity window has passed — request a new quote
`Wallet already exists`	Signing	Attempting to create a duplicate wallet
`Recipient not found`	Payout	The recipient ID does not exist in this workspace
`Insufficient balance`	Payout	Withdrawal address doesn’t have enough stablecoin to settle
`Order already settled`	Payout	Trying to cancel an order past `awaiting` status
`Agent has insufficient budget`	Agent	One of the 3 budget layers is exhausted
`Pending policies — finish the create flow`	Agent	Agent is mid-provisioning. Complete with `confirm-policies` or abandon with `DELETE /v1/agents/{id}`
`Passkey signature invalid`	Signing	The stamped activity does not match the unsigned payload

Error handling patterns

Check the status code first

4xx errors are your responsibility — inspect the message and fix the request. 5xx errors are server-side — retry with backoff.

Read the message field

The message is human-readable and explains the specific problem. Log it for debugging and surface a user-appropriate message in your UI.

Handle 401 and 403 separately

401 means unauthenticated (missing or invalid credentials). 403 means authenticated but not authorized (scope or permissions issue). These require different resolution paths.

Retry 429 and 5xx with backoff

Rate limit (429) and server errors (502, 503) are transient. Retry with exponential backoff: 1s, 2s, 4s, 8s. Give up after 3-4 attempts and surface the error to the user.

Treat 202 as 'pending', not an error

A 202 response means the action was accepted but is awaiting human approval (signing flows) or polling resolution (agent x402). It’s not a failure — poll the relevant resource until you get a final state.

Getting help

If you encounter a persistent 500 error or unexpected behavior, contact dev@relayer.fi with:

The full error response body
The request path, method, and (sanitized) payload
Your API key prefix (first 20 characters only — never share the full key)
The timestamp from the error envelope (we use it to locate server-side logs)

Get Started

Foundations

Error response format

HTTP status codes

4xx — client errors

5xx — server errors

2xx with caveats

Authentication errors

Agent-specific errors

Validation errors

Common business errors

Error handling patterns

Getting help

​Error response format

​HTTP status codes

​4xx — client errors

​5xx — server errors

​2xx with caveats

​Authentication errors

​Agent-specific errors

​Validation errors

​Common business errors

​Error handling patterns

​Getting help

Error response format

HTTP status codes

4xx — client errors

5xx — server errors

2xx with caveats

Authentication errors

Agent-specific errors

Validation errors

Common business errors

Error handling patterns

Getting help