Error Codes

All errors follow the same JSON structure:

{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE",
  "message": "Human-readable message",
  "details": {},
  "requestId": "req_abc123"
}

HTTP status codes are used semantically (400, 401, 403, 429, 500).

Error code reference

Code	HTTP	Description
`INVALID_METHOD`	400	Request method is invalid
`INVALID_PARAMETER`	400	A required parameter is missing or invalid
`INVALID_AGENT`	400	The agent code does not exist or is invalid
`INVALID_AGENT_ROLE`	403	The agent does not have the required role
`BLOCKED_AGENT`	403	The agent account is blocked
`INVALID_USER`	400	The user does not exist
`MAX_DEMO_USER`	400	Exceeded max demo users limit (500)
`INSUFFICIENT_AGENT_FUNDS`	400	Agent balance is not sufficient
`INSUFFICIENT_USER_FUNDS`	400	User balance is not sufficient
`DUPLICATED_USER`	409	A user with this code already exists
`INVALID_PROVIDER`	400	The game provider is invalid or not supported
`INTERNAL_ERROR`	500	Unexpected internal server error
`EXTERNAL_ERROR`	502	Error from an upstream provider
`API_CHECKING`	503	API is temporarily in maintenance mode
`AGENT_SEAMLESS`	400	Seamless integration error from the agent side

Auth errors

Code	HTTP	Description
`INVALID_SIGNATURE`	401	Solana signature verification failed
`EXPIRED_TOKEN`	401	Bearer token has expired (re-authenticate)
`MISSING_AUTH`	401	No Authorization header provided
`ADMIN_FORBIDDEN`	403	Wallet does not have the required permission

Rate limit errors

Code	HTTP	Description
`RATE_LIMITED`	429	Too many requests; retry after the `Retry-After` header value

Handling errors

const res = await fetch('/casino/play', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({ gameType: 'slots', wager: 1000, token: mintAddress }),
})
 
if (!res.ok) {
  const err = await res.json()
  console.error(`[${err.code}] ${err.message}`)
 
  if (err.code === 'EXPIRED_TOKEN') {
    // Re-authenticate
  } else if (err.code === 'INSUFFICIENT_USER_FUNDS') {
    // Show "not enough balance" UI
  }
}

📡 Endpoints 📦 Overview