Error Reference

HTTP Status Codes

Code	Meaning
200	Success
400	Bad Request — invalid input, missing fields
401	Unauthorized — missing or invalid API key / JWT
403	Forbidden — valid auth but insufficient permissions
404	Not Found — resource does not exist
409	Conflict — duplicate submission, already exists
429	Too Many Requests — rate limit exceeded

Error Response Format

Errors return a JSON body with an error field:

{
  "error": "Missing required fields: roundId, manifestJson, manifestHash, ticketCount"
}

Some endpoints include additional fields:

{
  "error": "A pending application already exists for this email",
  "applicationId": "app_xxx"
}

Common Error Codes

Error	Cause	Resolution
Missing required fields	Request body missing required parameters	Include all required fields
Invalid Ethereum address format	Address not 0x + 40 hex chars	Use valid EVM address
Invalid email format	Malformed email	Use valid email
Round not found	Invalid round ID	Check round exists via /api/public/rounds
Operator not found	Invalid operator ID	Verify operator is registered
Missing X-Ultima-Key header	No API key provided	Add X-Ultima-Key: ulk_...
Invalid API key	Wrong or revoked key	Verify key, request new if needed
Missing X-Application-Token header	Application status check without token	Add token from apply response
Invalid application token	Wrong token for application	Use token returned by apply
No webhook URL configured	Test webhook without URL	PUT /api/operator/webhook first
Unknown event type	Invalid eventType in test-webhook	Use one of the documented event types
Manifest already submitted for this round	Duplicate manifest	One manifest per operator per round
Round is not in OPEN or SEALING state	Wrong round state	Submit only when round is OPEN or SEALING

Rate Limits

• Public API: Generous limits for transparency queries
• Operator API: Authenticated rate limits apply; 429 returned when exceeded

Retry with exponential backoff on 429.