Error Handling

Proper error handling ensures your integration remains robust and provides a good user experience even when things go wrong.

HTTP Status Codes

Status Code	Meaning	Common Causes
`200`	Success	Request completed successfully
`400`	Bad Request	Invalid JWT, malformed request, or validation error
`401`	Unauthorized	Invalid API key, expired JWT, or missing authentication
`404`	Not Found	Resource doesn't exist
`500`	Internal Server Error	Unexpected server error

All JWT errors return a JSON object with a message field:

{
  "message": "jwt-expired"
}

Error Code	Description	Resolution
`jwt-expired`	JWT has passed its `exp` time	Generate a new JWT and retry the request
`jwt-invalid`	JWT signature verification failed	Check your API credentials and JWT generation logic
`jwt-missing-gameId`	JWT payload missing `iss` claim	Ensure `iss` is set to your `gameId` when generating JWT
`jwt-missing-playerId`	JWT payload missing `sub` claim	Include `sub` in the JWT payload
`jwt-not-yet-valid`	JWT `nbf` (not before) time hasn't been reached	Check system clock synchronization or wait
`unknown-gameId`	The `gameId` in JWT is not recognized	Verify your `gameId` is correct and registered

API Key errors return a simple string:

"invalid-api-key"

Error	Description	Resolution
`invalid-api-key`	API key or client ID is incorrect	Verify `x-api-key` and `x-client-id` headers are correct

JWTs expire after ~15 minutes. Cache them client-side while valid, then request a new one when expired and retry the failed request.

Flow:

Implement exponential backoff for 500 errors and network failures (1s, 2s, 4s, max 3-5 attempts). Don't retry 4xx client errors.

Check offer.status === 'claimable' before claiming rewards. Don't retry if status is 'claimed' or 'expired'.

Implement automatic reconnection with exponential backoff (max 10 attempts). Refresh JWT before reconnecting if expired.

Map technical errors to user-friendly messages:

API Error	User Message
`jwt-expired`	"Session expired. Please refresh the page."
`jwt-invalid`	"Authentication error. Please log in again."
`invalid-api-key`	"Service temporarily unavailable. Please try again later."
Network errors	"Connection error. Please check your internet."

Track error type, endpoint, and timestamp. Monitor error rates and alert on unusual patterns