Error Codes

All Diffusal API errors follow a consistent structure with an error code, HTTP status, and human-readable message. This page documents every error category returned by the API.

Error Response Format

{
  "code": "invalid_argument",
  "message": "symbols must be an array",
  "details": null
}

The code field maps to a standard gRPC/Encore error code. The message field contains a description specific to the failed request.

Error Reference

`unauthenticated` — HTTP 401

Returned when authentication is missing or invalid.

Context	Message	Fix
Missing session	`No auth data available`	Complete the SIWE auth flow to obtain a bearer token
Invalid SIWE nonce	`Invalid or expired nonce`	Request a fresh nonce from `POST /api/auth/siwe/nonce` before signing
Bad signature	`Invalid SIWE signature`	Ensure the wallet signing the SIWE message matches the address in the message
Bad signature format	`Invalid signature format`	Signature must be a valid hex string (0x-prefixed)
Missing SIWE fields	`Invalid SIWE message: no address` / `no chainId` / `no nonce`	Include all required fields in the SIWE message
Domain mismatch	`Domain mismatch: expected ...`	Set the SIWE domain to `api.testnet.diffusal.xyz`
Chain ID mismatch	`ChainId mismatch: expected ...`	Set the SIWE chain ID to match the target network
User not found	`User not found`	The wallet address has no associated account

`invalid_argument` — HTTP 400

Returned when request parameters fail validation.

Context	Message	Fix
Symbol validation	`symbols must be an array`	Pass symbols as a JSON array
Empty symbols	`At least one symbol is required`	Include at least one symbol in the request
Invalid symbol format	`Invalid symbol format`	Use the format `BTC-82000-C-1736409600` (underlying-strike-type-expiry)
Invalid wallet address	`Invalid wallet address`	Provide a valid checksummed Ethereum address
Invalid hex string	`seriesId must be a hex string`	Ensure IDs are 0x-prefixed hex strings
Missing required field	`{field} is required`	Include all required fields in the request body
Invalid amount	`amount must be a positive numeric string`	Pass amounts as positive decimal strings (e.g., `"100.5"`)
RFQ signature	`mmSignature must be a valid hex string`	Market maker signatures must be 0x-prefixed hex
Pagination	`limit must be greater than 0`	Set limit to a positive integer
Time range	`startTime must be before endTime`	Ensure the start timestamp is earlier than end

`permission_denied` — HTTP 403

Returned when the authenticated user lacks required permissions.

Context	Message	Fix
Admin required	`Admin access required`	This endpoint is restricted to admin wallets
Missing scope	`Missing required scope: trade`	Authenticate with an API key or session that has the `trade` scope
MMM required	`MMM membership required`	The wallet must be registered as a market maker member
Realtime auth	`Admin access required for monitoring stream`	Monitoring streams are admin-only

`not_found` — HTTP 404

Returned when a requested resource does not exist.

Context	Message	Fix
RFQ request	`(dynamic message)`	Check the request ID is valid and the RFQ auction has not expired
Order	`(dynamic message)`	Verify the order ID exists via `GET /api/mm/orders`
Series	`Series not found: {seriesId}`	The series may not be listed yet; check `GET /api/markets`

`resource_exhausted` — HTTP 429

Returned when rate limits are exceeded.

Context	Message	Fix
Rate limit	`rate limit exceeded`	Back off and retry after the cooldown period. See Rate Limits

`unavailable` — HTTP 503

Returned when a downstream service is temporarily unreachable.

Context	Message	Fix
Service not ready	`(dynamic message)`	The backend service is starting up or temporarily unavailable. Retry with exponential backoff
Upstream timeout	`(dynamic message)`	An internal service call timed out. Retry after a brief delay

`internal` — HTTP 500

Returned on unexpected server-side failures. These should be rare.

Context	Message	Fix
Unexpected error	`An unexpected error occurred`	Report the issue with your request ID if the error persists
Processing failure	`(dynamic message)`	An internal processing step failed. Retry or contact support

Retry Guidance

Error Code	Retry?	Strategy
`unauthenticated`	No	Re-authenticate, then retry the original request
`invalid_argument`	No	Fix the request parameters before retrying
`permission_denied`	No	Use an account with the required permissions
`not_found`	No	Verify the resource exists before retrying
`resource_exhausted`	Yes	Exponential backoff; respect `Retry-After` header if present
`unavailable`	Yes	Exponential backoff starting at 1 second
`internal`	Yes	Exponential backoff; report if persistent