Error Handling

All error responses follow a consistent JSON structure with an error code and a human-readable message. Use the error code for programmatic handling and the message for display purposes.

Status	Meaning	What to do
400	Bad request	Check your request body/params. Don't retry without fixing.
401	Unauthorized	Token is missing, expired, or invalid. Re-authenticate.
403	Forbidden	Action not allowed (no hints left, puzzle not done, etc.)
404	Not found	Puzzle or resource doesn't exist. Check the endpoint path.
409	Conflict	Token already consumed or device code already claimed. Start a new flow.
410	Gone	Device code expired (15-min TTL). Call `/cli/auth/start` again.
429	Rate limited	Wait for `Retry-After` header seconds before retrying.
503	Service unavailable	Server is down. Retry with exponential backoff.

Error response format

JSON

{
  "error": "invalid_word",
  "message": "Word is not in the dictionary or does not use the correct letters."
}

The CLI API uses a flat error format with top-level error and message fields. The Word API uses a nested format: { error: { code, message } }. Game-specific codes use snake_case (e.g. invalid_word), while infrastructure codes use SCREAMING_SNAKE_CASE (e.g. RATE_LIMIT_EXCEEDED).

Common error codes

Error code	Endpoint	Meaning
invalid_word	POST guess	Word not in dictionary or uses wrong letters
puzzle_in_progress	GET reveal	Can't reveal — user still has attempts remaining
no_hints_remaining	POST hint	All hints for this puzzle have been used
puzzle_complete	POST guess	Puzzle already solved or all attempts exhausted
expired_code	POST auth/poll	Device code has expired (15-min TTL) — restart the auth flow
consumed	POST auth/poll	Token already retrieved by a previous poll — token is one-time only
already_claimed	POST auth/complete	Device code already approved by another session

Always check the error field for programmatic handling. The message is human-readable and safe to show to users, but may change between API versions — don't match on it.

Was this page helpful?

Polling Reference

Community

Error Handling

Error response format

Common error codes

Community