Error Handling

Word API errors use a structured format with a machine-readable code and a human-readable message. Always match on the code, not the message — messages can change between versions.

Error format

JSON

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Daily API limit of 100 requests exceeded. Resets at 2026-02-11T14:30:00.000Z.",
    "resetAt": "2026-02-11T14:30:00.000Z"
  }
}

HTTP Status	Error Code	When It Happens	What to Do
400	INVALID_PARAMS	Non-integer or out-of-range params	Fix your query params. Don't retry.
400	INVALID_TIMEZONE	Unrecognized `tz` value on `/words/daily`	Use a valid IANA timezone (e.g. `America/New_York`).
401	UNAUTHORIZED	Missing, expired, or invalid API key	Check your key. Generate a new one if revoked.
429	RATE_LIMIT_EXCEEDED	Daily or per-minute limit hit	Wait until `resetAt` or check `Retry-After` header.
500	INTERNAL_ERROR	Server-side failure	Retry with exponential backoff.
503	SERVICE_UNAVAILABLE	Word pool or DB not ready	Wait a few seconds, then retry.

Handling errors in your code

bash

# Check rate limit headers on every response
curl -v "https://api.playanagrama.com/api/v1/words/random?count=5" \
  -H "Authorization: Bearer ak_your_key_here" 2>&1 | grep -i "x-ratelimit"

# X-RateLimit-Limit: 1000
# X-RateLimit-Remaining: 995
# X-RateLimit-Reset: 1739232000

# If you get a 429, check the Retry-After header:
# Retry-After: 3600

The SDKs automatically parse error responses into typed exceptions. You can catch APIError (Python) or check err.status (TypeScript) to handle specific cases. The resetAt field on 429 errors is an ISO timestamp — parse it to schedule your next retry.

Was this page helpful?

Get Wordset Tips & Best Practices

Community

Error Handling

Error format

Handling errors in your code

Community