Errors and Limitations

Common error responses

Authentication and rate limit failures may be returned early by the gateway or middleware:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authorization Bearer or Key token is required"
  },
  "request_id": "..."
}

Rate limit example:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded, please try again later"
  },
  "request_id": "..."
}

Model identifier not found:

{
  "detail": "App not found: not_exists"
}

Model not authorized:

{
  "detail": "Model not allowed for this user"
}

Webhook unsupported:

{
  "detail": "webhook not supported"
}

Runtime failure:

{
  "detail": "Runtime execution failed"
}

Unsupported capabilities

Webhook

Webhook is not currently supported. Requests carrying webhook callback information in the request body, query parameters, or request headers are rejected:

curl -X POST "${BASE_URL}/v1/queue/${ENDPOINT}" \
  "${COMMON_HEADERS[@]}" \
  -d '{
    "prompt": "a cinematic photo of a cat astronaut",
    "webhook_url": "https://example.com/hook"
  }'

400

{
  "detail": "webhook not supported"
}

Warning

The current version does not provide callback delivery. Use status_url to poll task status.

SSE stream

curl "${BASE_URL}/v1/queue/${ENDPOINT}/requests/${REQUEST_ID}/status/stream" ...

404

{
  "detail": "SSE streaming not supported"
}

Sync

The current multimodal queue only provides an asynchronous task protocol. It does not provide a synchronous generation endpoint.

curl -X POST "${BASE_URL}/v1/queue/${ENDPOINT}/sync" ...

404

{
  "detail": "Not Found"
}

Handling suggestions

• Save request_id after task creation succeeds; it is needed for later status polling, result retrieval, and cancellation.
• When polling, use only status to determine whether the task is terminal; after COMPLETED, check error to determine success or failure.
• An incomplete response_url request may return HTTP 202; do not treat it as an abnormal task.
• For 404 Request not found, do not retry for too long; it usually means the request_id is incorrect, the endpoint does not match, or access is not permitted.
• For 5xx / 502, use limited retries. Do not retry create-task requests indefinitely, to avoid creating duplicate tasks.