When a Fhddos API call fails, the platform returns a structured error object with a consistent shape across all API interfaces. The exact outer envelope may vary depending on the protocol style you’re using — OpenAI-compatible or Anthropic-compatible — but the core fields and their semantics are the same everywhere.
Error Response Structure
Every error response body follows this format:
{
"error": {
"code": "invalid_request_error",
"message": "Invalid image size. The longest edge must be <= 4096. (request id: 20260604120000abcdef)",
"type": "invalid_request_error",
"request_id": "20260604120000abcdef",
"upstream_request_id": "req_abc123"
}
}
| Field | Description |
|---|
error.code | Machine-readable error code. Upstream business errors preserve upstream semantics. |
error.message | Human-readable message that is safe to display to users or write to logs. |
error.type | Broad error category. Upstream business errors preserve upstream semantics. |
error.request_id | Platform request ID — include this in every support ticket. |
error.upstream_request_id | Upstream provider’s request ID, if the provider returned one. |
HTTP Status Codes
Fhddos assigns stable semantic meaning to each HTTP status code so your error-handling logic stays predictable regardless of which upstream provider handled the request:
| Code | Platform meaning | Upstream behavior |
|---|
400 | Invalid request parameters, unsupported model capability, or content input issue | Upstream 400 and readable message preserved |
401 | Invalid or missing Fhddos API key | Upstream account or key errors are never surfaced as a client-side 401 |
402 | Account, token, or organization quota exhausted | Upstream balance, billing, and quota issues are wrapped as 503 |
403 | No access to model, group, IP allowlist, or resource | Upstream permission and account-ban errors are wrapped as 503 |
429 | Fhddos or upstream rate limit triggered | Upstream 429 is preserved with rate-limit semantics; sensitive details are removed |
502 | Upstream returned an invalid or bad response, or gateway error | Preserved or sanitized |
503 | Upstream channel account, permission, balance, or capacity temporarily unavailable | Wrapped operational supply error |
504 | Upstream timeout or network connection issue | Preserved or sanitized |
error.type | error.code | Meaning | Recommended action |
|---|
system_error | upstream_channel_unavailable | Upstream channel account, key, or permission is temporarily unavailable | Retry later; open a ticket if the error persists |
system_error | upstream_capacity_unavailable | Upstream balance, billing, quota, or capacity is temporarily unavailable | Retry later; open a ticket if the error persists |
Content Safety and Image Blocking
When an upstream provider explicitly blocks a request due to content safety or image filtering, Fhddos preserves the user-understandable reason — for example, “image filtered by safety policy” — without exposing the provider’s internal fields.
| Upstream internal signal | What you see |
|---|
finishReason=IMAGE_SAFETY | Internal field removed; “image filtered by safety policy” semantic preserved |
finishReason=PROHIBITED_CONTENT | Internal field removed; content safety semantic preserved |
promptFeedback.blockReason=PROHIBITED_CONTENT | Internal field removed; input content safety semantic preserved |
no candidates / empty_candidates | Implementation detail removed; upstream readable reason or platform safe message preserved |
Do not retry content safety or image blocking errors directly. Modify your prompt, text, or image first, then resubmit the request.
The no_image_generated Error
Gemini image models may process a request and bill for tokens without actually producing an image. In this case, Fhddos returns error.code=no_image_generated. If the request was already billed, the error response includes a usage field so you can reconcile charges:
| Interface style | Usage fields |
|---|
| OpenAI-style synchronous image endpoint | usage.input_tokens, usage.output_tokens, usage.total_tokens |
Gemini native generateContent | usageMetadata.promptTokenCount, usageMetadata.totalTokenCount |
| Async image task query | usage.prompt_tokens, usage.input_tokens, usage.output_tokens |
usage field is omitted.
Retry Guidance
| Scenario | Recommendation |
|---|
| Content safety or image blocked | Don’t retry — modify your input first |
| Invalid request params, unsupported model capability, context length, or image size | Don’t retry — fix the request |
Upstream rate limit (429) | Retry with delay and reduced concurrency |
| Upstream timeout or network error | Retry; add a business-side timeout and idempotency handling for long-running tasks |
Upstream 5xx or bad response | Short retry; file a support ticket if the issue persists |
upstream_channel_unavailable or upstream_capacity_unavailable | Retry later; file a support ticket if the issue persists |
What Fhddos Sanitizes from Upstream Errors
Fhddos removes the following categories of information from upstream responses before they reach you:
- Upstream API keys, account details, permissions, and balance or billing specifics
- Upstream provider SDK information, exception stack traces, internal request IDs, and URLs
- Internal channel, group, tenant, organization, and workspace names
- Raw bad-response status codes, multi-level request ID chains, and unredacted upstream JSON
To investigate a specific failure, provide error.request_id in your support ticket. The Fhddos support team can use that ID to view the complete internal trace and the original upstream error.
In production, log error.request_id, the HTTP status code, error.code, and error.type for every failed request. Avoid branching your error-handling logic on error.message — message text can vary across upstream providers and may change over time.
