Error Codes
Complete reference of Filed API error codes, HTTP status codes, and how to handle them.
Error Format
All errors return a JSON body with an error object containing a machine-readable code and human-readable message:
{
"error": {
"code": "rate_limit_exceeded",
"message": "You have exceeded your monthly lookup limit.",
"limit": 100,
"reset": "2026-03-01T00:00:00Z"
}
}Error Code Reference
| HTTP Status | Code | Description |
|---|---|---|
| 400 | invalid_params | Missing or invalid query parameters |
| 401 | unauthorized | Missing or invalid API key |
| 403 | tier_insufficient | Endpoint requires a higher tier plan |
| 404 | not_found | Entity not found |
| 429 | rate_limit_exceeded | Monthly or per-minute limit exceeded |
| 500 | internal_error | Something went wrong on our end |
| 502 | upstream_error | State data source temporarily unavailable |
Handling Errors
Best practices for error handling:
- 401 Unauthorized — Check that your API key is correct and included in the Authorization header.
- 429 Rate Limited — Back off and retry after the time indicated in
X-RateLimit-Reset. Consider upgrading your plan if you consistently hit limits. - 502 Upstream Error — A state data source is temporarily unavailable. Retry after a short delay (5-10 seconds). These are usually transient.
- 500 Internal Error — If persistent, contact support. Include the request URL and timestamp.
Rate Limit Headers
Every response includes rate limit information:
| Header | Description |
|---|---|
X-RateLimit-Remaining | Number of requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp when the rate limit resets |