Error Handling

Error format

SeaCloud LLM may return simple errors or OpenAI-style error objects. Clients should handle errors using both HTTP status codes and error codes.

Authentication errors

Missing token

{
  "error": "missing authentication token"
}

Invalid key

{
  "error": "invalid_api_key"
}

Insufficient balance

{
  "error": "insufficient balance"
}

OpenAI-style error

{
  "error": {
    "message": "Request rejected by quota policy.",
    "type": "rate_limit_error",
    "param": null,
    "code": "quota_exceeded"
  }
}

Common HTTP statuses

Status code	Common reason	Handling suggestion
401	Missing authentication token	Check Authorization or x-api-key
403	API Key is invalid or expired, balance is insufficient, or the model is not authorized	Do not retry indefinitely. Resolve account or permission issues first
404	Unsupported path or incorrect public entry	Confirm that the public path includes /llm
429	Quota or rate limit	Retry with Retry-After or exponential backoff
502/503/504	Service temporarily unavailable or request timeout	Record X-Request-Id and contact the platform for troubleshooting

Client suggestions

• Record HTTP status code, response body, and X-Request-Id.
• Use limited backoff retries only for 429 and some 5xx responses.
• For authentication, balance, model permission, and path errors, fix the configuration before retrying.
• If a streaming request disconnects midway, do not assume the request will not generate usage or billing.