Getting Started
Error handling
Updated: July 4, 2025
The FireTail API follows standard HTTP status codes to indicate whether a request was successful or failed.
HTTP status code categories
Success codes (2xx):
Codes in the 2xx range indicate that your request was successful and processed as expected.
Client error codes (4xx):
Codes in the 4xx range indicate an error that failed given the information provided. These errors are typically caused by issues with your request, such as missing parameters, invalid data, or insufficient permissions.
Server error codes (5xx):
Codes in the 5xx range indicate an error with FireTail's servers. These errors are rare and typically indicate temporary issues on FireTail's end.
Detailed error codes
| Code | Status | Meaning | Common Causes | Action | Example Scenarios |
|---|---|---|---|---|---|
| 200 | OK | Everything worked as expected | N/A | Process the response data normally | Retrieved API list, created credentials, obtained token |
| 400 | Bad Request | The request was unacceptable, often due to missing parameters | Missing fields, malformed JSON, invalid parameters | Review and fix request parameters | Invalid key or missing property |
| 401 | Unauthorized | No valid JWT or API key provided | Missing/expired token, invalid token, wrong credentials | Obtain new token and retry | Missing Authorization header, token expired, wrong client credentials |
| 403 | Forbidden | API key doesn’t have permissions to perform the request | Insufficient scopes, downgraded role, revoked access | Check credentials and required scopes | Read-only key trying to write, missing scope, user downgraded |
| 404 | Not Found | The requested resource doesn’t exist. | Incorrect ID/UUID, resource deleted, wrong endpoint URL | Verify identifier and endpoint | Wrong organization UUID, deleted reference, typo in endpoint URL |
| 429 | Too Many Requests | Too many requests hit the API too quickly | Rate limits exceeded, request burst without throttling | Implement exponential backoff with jitter | Exceeding 500/sec GET or 50/sec POST |
| 500 | Internal Server Error | Something went wrong on the server (FireTail). | Server malfunction, internal error, database issue | Retry after delay, contact support if persistent | Temporary system failure |
| 502 | Bad Gateway | Invalid response from upstream server. | Downstream service crashed, gateway timeout | Retry after delay | Communication issue between services |
| 503 | Service Unavailable | Server is temporarily unavailable | Maintenance, high load | Wait and retry | Scheduled downtime, temporary overload |
| 504 | Gateway Timeout | Upstream server failed to send response in time | Slow downstream API or service | Optimize or retry later | Long wait on external system call |