Reference

Response Codes

Understand the HTTP status codes returned by the API.

Success Codes

200OK

The request was successful. The response body contains the requested data.

{
  "level": "A1",
  "total": 834,
  "returned": 10,
  "data": [...]
}

400Bad Request

The request was malformed. Check your parameters.

Common causes: Invalid CEFR level, invalid parameter format

{
  "detail": "Invalid level: X5. Use: a1, a2, b1, b2, c1"
}

401Unauthorized

Authentication failed. Your API key is missing or invalid.

Solution: Include a valid X-API-Key header

{
  "detail": "Invalid API key. Get a key at /register (coming soon)"
}

404Not Found

The requested resource doesn't exist.

Solution: Check the endpoint URL spelling

{
  "detail": "Not Found"
}

422Validation Error

The request was well-formed but contains invalid data.

Common causes: Missing required parameter, value out of range

{
  "detail": [
    {
      "loc": ["query", "level"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

429Too Many Requests

You've exceeded the rate limit. Wait before making more requests.

Solution: Implement exponential backoff, wait and retry

{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}

500Internal Server Error

Something went wrong on our end. This is rare.

Solution: Wait a moment and retry. If it persists, contact support.

{
  "detail": "Internal server error"
}