Error Codes¶

A quick reference for errors and rate limits when calling Genesis / model APIs. For service-specific error codes, response-body field names, and rate-limit values, follow the live API and key configuration. Handle codes not listed in the table according to the API response.

For authentication, endpoints, and examples, see Developer and Genesis.

Authentication¶

The model API uses OpenAI-compatible authentication and accepts only:

Authorization: Bearer <API_KEY>

As with the OpenAI SDK, set api_key to the Genesis Key and point base_url to Genesis. Create an API Key under “Keys” in Genesis. The UI might mask the key; when copying it, use the actual value. Do not commit it to a code repository.

HTTP Statuses and Handling¶

Based on HTTP and OpenAI-compatible conventions:

Status code	Meaning	Recommended action
400	Invalid request parameters	Check fields and values; do not retry blindly
401	Authentication failed	Check whether the Key is correct, disabled, or expired; verify the header name
403	Permission denied / model not enabled for the key	Enable the model for the key or use a different key
404	Endpoint or model does not exist	Verify the Base URL and `model`
429	Rate limit reached or quota exhausted	Retry with backoff; or request a higher quota / reduce concurrency / wait for the daily quota to reset
5xx	Server error	Retry after backoff; idempotent requests can be retried safely

Error response skeleton (the actual API determines the structure):

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit reached for this API key.",
    "code": "429"
  }
}

Rate Limits and Quotas¶

Calls are subject to two layers of constraints. Reaching either limit rejects the request:

Layer	Description
Key-level rate	Concurrency, RPM (requests per minute), and similar limits
Key-level quota	Total quota, daily quota, and similar limits

A rate limit commonly produces HTTP 429. If the response includes Retry-After, wait for the specified number of seconds first.

Retry recommendation: Use exponential backoff + jitter for 429 and 5xx. Do not retry other 4xx responses.

Symptom Reference¶

Symptom	Possible cause	Action
Returns 429	Rate limit reached or quota exhausted	Reduce concurrency and back off; increase the quota or wait for the daily quota to reset
Quota is repeatedly exhausted	Quota is too low or multiple business lines share one Key	Use separate Keys by business line and monitor the usage dashboard
403 for a specific model	Model is not in the key’s available model scope	Change the model or the key configuration
Model suddenly becomes unavailable	Marketplace status issue / model removed	Check the model status in Genesis and switch to an available model of the same type; you can also enable availability notifications
Authentication failed	Key is wrong / expired, or `Authorization: Bearer` was not used	Verify the OpenAI-style request header and Key; recreate the Key if necessary
OpenAI SDK error	Base URL does not point to Genesis, or `api_key` is not a Genesis Key	Correct `base_url` and `api_key`
Billing differs from expectations	Cache billing or API-type billing rules differ	Compare the integration instructions with the usage details
Request rejected for insufficient balance	Insufficient Credit	Add funds under Costs and Billing, then retry
Undocumented error code	—	Follow the API response; if necessary, provide the request and response when contacting support

Parameters and billing rules differ among API types (Chat / Embeddings / OCR / Image / Video / TTS / ASR, and others). Before calling an API, consult the integration instructions for that type.