Errors - GENGEN API

GENGEN errors use a stable JSON envelope:

{
  "error_code": "gengen.model_required",
  "error_params": {
    "field": "model"
  },
  "error": "A model is required"
}

Field	Type	Description
`error_code`	string	Stable machine-readable code
`error_params`	object	Optional structured context
`error`	string	Optional human-readable message

Common status codes

HTTP status	Meaning
`400`	Invalid JSON, query parameters, model, mode, or provider input
`401`	Missing or invalid API key
`402`	Insufficient available balance
`403`	Revoked, expired, or unauthorized API key
`404`	The task does not exist in the current workspace
`501`	The selected provider does not support the operation
`5xx`	GENGEN or an upstream provider could not complete the request

Handling errors

Branch on error_code, not the message text.
Log the HTTP status, error_code, and request correlation data without logging API keys.
Retry transient 5xx and rate-limit responses with exponential backoff and jitter.
Fix 4xx request errors before retrying.
Treat task-not-found responses as non-disclosing. The retrieve endpoint does not reveal tasks that are inaccessible to the current API key.

Provider error codes

When a response includes a BytePlus ModelArk error code, search the provider error reference for its description. Continue to use the GENGEN error_code and HTTP status as the stable values in application logic.

​Common status codes

​Handling errors

​Provider error codes

Common status codes

Handling errors

Provider error codes