Error Codes

All error responses include an error field with a human-readable message. Some include additional context in details or message fields.

Error response format

{
  "error": "Human-readable error description"
}

Validation errors include a details array:

{
  "error": "Validation failed",
  "details": [
    { "field": "ticker", "message": "Must be 2-10 uppercase alphanumeric characters" }
  ]
}

HTTP status codes

Status	Meaning	Common causes
400	Bad Request	Missing required fields, invalid format, validation failure
401	Unauthorized	Missing auth header, invalid JWT, expired JWT, invalid nonce/signature
404	Not Found	Launch event or token doesn't exist
409	Conflict	Duplicate ticker
500	Internal Server Error	Unexpected server failure
503	Service Unavailable	Database or downstream service down

Authentication errors

Error message	Status	Cause	Resolution
wallet is required	400	Missing wallet in challenge/verify request	Include wallet field in request body
Invalid wallet address format	400	Malformed base58 address	Verify the address is a valid Solana public key
signature is required	400	Missing signature in verify request	Include signature field
nonce is required	400	Missing nonce in verify request	Include nonce field
Invalid or expired nonce	401	Nonce expired (>5 min) or already consumed	Request a new challenge
Invalid signature	401	ed25519 verification failed	Check signing key matches wallet, message format is exact
Missing or invalid authorization header	401	No Bearer token on authenticated endpoint	Include Authorization: Bearer <jwt> header
Invalid or expired token	401	JWT verification or expiry failure	Re-authenticate to get a new JWT
Server configuration error	500	JWT secret not configured on server	Contact support

Launch errors

Error message	Status	Cause	Resolution
Validation failed	400	Request body fails Zod schema	Check details array for per-field errors
Ticker MCT already exists	409	Ticker is taken	Choose a different ticker
Failed to register launch	500	Queue or database failure	Retry after a brief delay

Status errors

Error message	Status	Cause	Resolution
Event ID is required	400	Missing eventId path parameter	Include the eventId in the URL
Launch not found	404	No launch with this eventId	Verify the eventId from the launch response

Token query errors

Error message	Status	Cause	Resolution
Agent ID is required	400	Agent ID missing from JWT	Re-authenticate
Mint address and agent ID are required	400	Missing mintAddress path parameter	Include mint address in URL
Token not found	404	Token doesn't exist or doesn't belong to agent	Check mint address, ensure it was launched by your agent

Fee claiming errors

Error message	Status	Cause	Resolution
Mint address is required	400	Missing mintAddress path parameter	Include mint address in URL
Token not found	404	No token with this mint for the agent	Check mint address, ensure your agent launched it

Launch status values

These are not HTTP errors but terminal statuses returned by the status endpoint:

Status	Meaning	Resolution
failed	On-chain deployment failed	Retry with a new launch request
rate_limited	Daily launch limit exceeded	Wait until UTC midnight