Error Codes
TrueEntropy uses conventional HTTP status codes and structured JSON error responses. Every error includes a machine-readable code and a human-readable message.
Error Response Format
Error Response
{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded. Retry after 12 seconds.",
"retry_after": 12
}
}
HTTP Status Codes
| Status | Meaning |
|---|---|
| 200 | Success - request completed, random values returned |
| 400 | Bad Request - invalid parameters (see specific error code) |
| 401 | Unauthorized - missing or invalid API key |
| 403 | Forbidden - key lacks required scope |
| 404 | Not Found - endpoint or resource does not exist |
| 429 | Rate Limited - too many requests, retry after specified delay |
| 500 | Internal Error - server-side issue, contact support |
| 503 | Service Unavailable - maintenance or pool exhaustion |
Error Codes Reference
| Code | HTTP | Description |
|---|---|---|
| auth_missing | 401 | No Authorization header provided |
| auth_invalid | 401 | API key is invalid, revoked, or expired |
| auth_scope | 403 | API key lacks the required scope for this endpoint |
| invalid_count | 400 | count parameter out of allowed range |
| invalid_range | 400 | min must be less than max |
| unique_impossible | 400 | Unique values requested but range too small |
| invalid_encoding | 400 | encoding must be hex or base64 |
| invalid_type | 400 | Batch type must be integers, floats, bytes, or uuid |
| invalid_precision | 400 | precision must be between 1 and 16 |
| invalid_length | 400 | Bitstring length out of allowed range |
| rate_limited | 429 | Rate limit exceeded - check X-RateLimit-Reset header |
| quota_exceeded | 429 | Monthly request quota exhausted |
| pool_exhausted | 503 | Entropy pool temporarily depleted (rare) |
| internal_error | 500 | Unexpected server error - includes request_id for support |
| cert_not_found | 404 | Certificate ID does not exist |
Handling Errors
error_handling.py
from trueentropy import TrueEntropy, TrueEntropyError, RateLimitError
client = TrueEntropy(api_key="te_live_YOUR_KEY")
try:
result = client.integers(count=5)
except RateLimitError as e:
print(f"Rate limited. Retry after {e.retry_after}s")
except TrueEntropyError as e:
print(f"Error {e.code}: {e.message}")