Errors
JSON error shape, HTTP status codes, and resilient client patterns for the Frametail API.
Frametail HTTP APIs use conventional status codes and a small JSON envelope so clients can branch predictably.
Response shape
Failed requests return JSON similar to:
{
"error": "Human readable message"
}Some 403 responses may include extra fields such as required and provided permission lists when using middleware that enforces scopes. Treat unknown fields as informational.
Status codes
| Code | Meaning | What to do |
|---|---|---|
| 400 | Bad request — missing header, malformed JSON, invalid query args, or validation failure. | Fix the input; retrying without changes will not succeed. |
| 401 | Authentication failed — missing or invalid API key. | Refresh credentials from the dashboard; check for whitespace or wrong environment. |
| 403 | Authenticated but not allowed for the operation. | Confirm API key permissions with your admin. |
| 404 | Unknown resource or project key for the organization. | Verify ids and X-Project-Key; handle as a genuine miss. |
| 500 | Unexpected server error. | Retry with exponential backoff; if failures persist, capture the timestamp and message for support. |
Timeouts and retries
- Use conservative client timeouts for long-running calls such as benchmark starts; poll task endpoints rather than blocking indefinitely.
- For 500 responses, retry with jittered backoff. Do not blindly retry 400 or 404 responses.
Logging
Log status codes and error strings, not raw API keys. Prefer structured logs keyed by trace id or benchmark id to correlate with the Frametail UI.