Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.relayer.fi/llms.txt

Use this file to discover all available pages before exploring further.

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"
}
FieldTypeDescription
successbooleanAlways false for errors
messagestringHuman-readable error description
statusCodenumberHTTP status code (mirrors the response status)
timestampstringISO 8601 timestamp of when the error occurred
pathstringThe 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

StatusNameMeaning
400Bad RequestRequest body or query parameters are invalid or missing required fields
401UnauthorizedAPI key / JWT / HMAC is missing, malformed, expired, or invalid
402Payment RequiredAn x402-gated resource requires a USDC payment (Agent Kit only)
403ForbiddenCaller is authenticated but lacks scope or permissions for this endpoint
404Not FoundThe requested resource does not exist (wrong ID, deleted, or wrong path)
409ConflictOperation conflicts with existing state (e.g., duplicate resource)
422Unprocessable EntityRequest is well-formed but fails business validation (e.g., insufficient balance)
429Too Many RequestsRate limit exceeded — back off and retry

​
5xx — server errors

StatusNameMeaning
500Internal Server ErrorUnexpected server-side error — contact support if persistent
502Bad GatewayAn upstream service returned an error
503Service UnavailableAPI is temporarily unavailable — retry with exponential backoff

​
2xx with caveats

StatusMeaning
202 AcceptedReturned by signing endpoints when the action is queued for human approval. Body contains { approvalId }. Poll /v1/signing/approvals/{id} until resolved

​
Authentication errors

{
  "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.

​
Agent-specific errors

Agent endpoints use structured error codes inside the body so the SDK can dispatch programmatically:
error codeHTTPCause
invalid_auth401Missing HMAC headers, agent not found, or signature mismatch
expired_timestamp401x-request-timestamp drift exceeds ±60 seconds
agent_killed401Agent status is killed — re-provision before retrying
budget_exhausted402 / 403One or more budget layers exhausted. Response includes failedLayers: ["infra" | "tokens" | "payments"]
kill_switch_active503Global kill switch tripped — payments blocked (fail-safe)
x402_payment_required402The downstream x402 resource requires payment — handled by x402fetch
approval_required202Payment 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)KitCause
Quote has expiredPayoutThe quote’s validity window has passed — request a new quote
Wallet already existsSigningAttempting to create a duplicate wallet
Recipient not foundPayoutThe recipient ID does not exist in this workspace
Insufficient balancePayoutWithdrawal address doesn’t have enough stablecoin to settle
Order already settledPayoutTrying to cancel an order past awaiting status
Agent has insufficient budgetAgentOne of the 3 budget layers is exhausted
Pending policies — finish the create flowAgentAgent is mid-provisioning. Complete with confirm-policies or abandon with DELETE /v1/agents/{id}
Passkey signature invalidSigningThe stamped activity does not match the unsigned payload

​
Error handling patterns

1

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.
2

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.
3

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.
4

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.
5

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)