Errors
Handle common API failures with predictable retry and user-facing behavior.
Fluo returns standard HTTP status codes. Your application should handle authentication, validation, rate limiting, and transient server failures explicitly.
Common Status Codes
| Status | Meaning | Recommended handling |
|---|---|---|
400 | The request shape or parameter is invalid. | Fix the request before retrying. |
401 | Authentication failed or a key is missing. | Check credentials and headers. |
403 | The key or user is not allowed to access the resource. | Check project, agent, domain, or key scope. |
404 | The requested resource was not found. | Check IDs and project context. |
422 | Validation failed. | Show a developer-facing error or log the validation detail. |
429 | Rate limit or usage cap exceeded. | Back off, then retry later if appropriate. |
500 | Unexpected server error. | Retry with exponential backoff and log the request ID if available. |
Error Shape
Errors generally include a detail field.
{
"detail": "Invalid API key"
}
Validation errors may include a type.
{
"detail": "query is required",
"type": "ValidationError"
}
Retry Guidance
| Situation | Retry? |
|---|---|
400, 401, 403, 404, 422 | No. Fix the request or permissions first. |
429 | Yes, after waiting. Respect Retry-After when present. |
500 or network timeout | Yes, with exponential backoff. |
User-Facing Failures
For chat UIs, keep messages simple:
- "I could not connect. Try again in a moment."
- "This assistant is not available on this domain."
- "The uploaded file is too large or unsupported."
Log the detailed error server-side for debugging.