2.6 Common Integration Errors

Business errors always return HTTP status 200; judge by code, do not rely on the HTTP status code.

HTTP	code	message	Cause
200	0	success (but response fields are all empty strings)	Client parsed using camelCase; responses are always snake_case, adjust the JSON tags
200	10000	authentication failed	Signature / X-Body-Hash mismatch. GET must use sha256("{}"); POST must use the JCS hash of the body
200	10000	missing body-hash in metadata	X-Body-Hash header not sent
200	10020	ticket_id is required / invalid ticket_id format	Missing ticket_id or not in UUID format
200	10020	—	Time must be RFC3339 UTC (e.g. 2026-05-19T00:00:00Z), not a millisecond timestamp
200	10030	... not found	Queried object does not exist, or does not belong to this agent
200	10040	... already exists	Another request with the same ticket_id is currently being processed; the entry is never posted twice — resend the exact same request shortly to obtain the result of the first call
200	10050	ticket_id already used with a different amount (recorded 100, requested 100.5)	The same ticket_id has already been used but this call carries a different amount or currency; do not retry — use a new ticket_id if the amount must change
200	10060	rate limit exceeded	Exceeded the per-minute rate limit for this endpoint
200	10080	internal server error	Internal server error
200	20160	insufficient balance	Player balance is insufficient to complete the withdrawal
4xx	—	—	HTML error page, request did not pass the gateway (IP not whitelisted, incorrect Content-Type, GET sent with a body, etc.)

Most signature problems stem from body canonicalization or X-Body-Hash handling in the HMAC Verification Flow; when you hit 10000, check these two first.