Error Codes

SilvaMux's error format depends on the API type. This page summarizes the common error format, model-call error codes, and retry advice.

Gateway API Errors (Model Calls)

The error format of chat, image, and video model APIs is determined by the model protocol, rendered in one of four shapes — OpenAI / Anthropic / Gemini / Volcengine — with a unified code string.

{
  "error": {
    "message": "Detailed error message",
    "type": "gateway_error",
    "code": "ERROR_CODE"
  }
}

When the model side returns 4xx/5xx, SilvaMux passes the error response through after sanitization, preserving the HTTP status code; no charges are incurred in that case.

Gateway API Error Codes

Chat, image, and video model calls share the following error codes:

Code	HTTP	Description
`MODEL_REQUIRED`	400	Request body missing the `model` field
`MODEL_NOT_FOUND`	400	Model does not exist or is unavailable
`INVALID_REQUEST`	400	Invalid request parameters
`INVALID_REQUEST_BODY`	400	Failed to parse the request body
`UNAUTHORIZED`	401	Authentication failed (invalid API key/JWT)
`MODEL_ACCESS_DENIED`	403	Organization lacks the permission flags required by the model
`INSUFFICIENT_BALANCE`	402	Insufficient balance
`PRE_DEDUCT_FAILED`	400/402	Pre-deduction failed (bad parameters = 400, storage failure = 402)
`RATE_LIMITED`	429	Rate limit hit (see Rate Limits)
`UPSTREAM_UNAVAILABLE`	502	Failed to send the request to the model side
`UPSTREAM_HTTP_ERROR`	502	Model side returned 4xx/5xx
`UPSTREAM_PROVIDER_ERROR`	502	Model-side business error
`UPSTREAM_INVALID_RESPONSE`	502	Model-side response could not be parsed
`INTERNAL`	500	Internal error

Image Generation Only

Code	HTTP	Description
`REQUEST_TOO_LARGE`	413	Request body exceeds 64MB
`CONCURRENCY_LIMIT_EXCEEDED`	429	Image generation concurrency cap

Video & Tasks Only

Code	HTTP	Description
`INVALID_CALLBACK_URL`	400	Invalid callback URL
`CONCURRENCY_LIMIT_EXCEEDED`	429	Video generation concurrency cap

Task cancellation errors:

HTTP	Code	Description
404	`NOT_FOUND`	Task not found
409	`INVALID_STATE`	Task is not in the queued state
502	`UPSTREAM_CANCEL_FAILED`	Model-side cancellation failed

Billing / Business API Errors (Management APIs)

Account, billing, and proprietary asset management APIs use an RFC 7807-style body:

{
  "status": 400,
  "detail": "Detailed error message",
  "type": "tag:hub,2026-03:ERROR_CODE"
}

Validation errors include an errors array:

{
  "status": 422,
  "detail": "validation failed",
  "type": "tag:hub,2026-03:VALIDATION_FAILED",
  "errors": [{"location": "body.email", "message": "required"}]
}

Error codes of the customer query APIs (balance/usage) are listed in Query Balance and Query Usage.

Retry Advice

HTTP status	Advice
400	Do not retry; fix the request parameters
401	Do not retry; check your credentials
402	Do not retry; top up first
403	Do not retry; contact an administrator
429	Retry after waiting; exponential backoff recommended
500	Retrying is fine; wait 1–5 seconds between attempts
502	Retrying is fine; the model side is temporarily unavailable

Request IDs

Every response carries an X-Request-Id header (format REQ-xxxx). Provide this ID when troubleshooting. You may also set your own X-Request-Id on requests; the system keeps it.