Errors - ZeroGen Docs

Every error uses one envelope, whether a request is refused or a run or one of its outputs fails:

{
  "error": {
    "code": "validation_failed",
    "message": "Too big: expected number to be <=4",
    "param": "output.count",
    "retryable": false
  }
}

Field	Description
`code`	A stable, machine-readable code in lowercase `snake_case`. Codes are part of the contract: branch on `code`.
`message`	A sentence for people. Messages can change, so don’t parse them.
`param`	Optional. The request field, header, or query parameter at fault, such as `inputs[0].url`, `Idempotency-Key`, or `cursor`. Nested fields use dots, and array items use `[index]`.
`retryable`	Whether sending the same request again can succeed.
`details`	Optional. An object with more facts about the error. Each code below says which details it carries.

A failed run reports the envelope’s inner object as its error, and each failed output reports one as its own error.

Retry errors

Retry a request only when retryable is true. Back off between attempts, and for a 429, wait at least the number of seconds in the Retry-After header. Send the same Idempotency-Key on each retry of a POST, so that a retry never starts a second run. For details, see Idempotency.

Request errors

Status	Code	Meaning
`400`	`invalid_request`	The request is malformed: the body isn’t valid JSON, it has an unknown field, a query parameter is unknown or sent twice, the `Idempotency-Key` header isn’t 1 to 255 printable ASCII characters, or an endpoint that takes no body received one.
`405`	`invalid_request`	The endpoint doesn’t accept this method. The `Allow` header lists the methods it accepts.
`413`	`invalid_request`	The request body is larger than 128 KiB.
`415`	`invalid_request`	The request body isn’t sent as `application/json`.
`400`	`validation_failed`	A value is invalid for the endpoint or for the model’s request schema, or a `cursor` doesn’t match the filters sent with it.
`400`	`model_unavailable`	The model isn’t available to your organization, or it’s past its sunset date. `param` is `model`.
`400`	`input_import_failed`	ZeroGen couldn’t import a URL input. `param` names the input, such as `inputs[1].url`. Nothing is charged.
`401`	`invalid_api_key`	The API key is missing, malformed, unknown, revoked, or expired, or its prefix names the wrong mode.
`402`	`insufficient_balance`	Your organization’s available balance can’t cover the run’s quote. `details` carries `availableMicroUsd` and `requiredMicroUsd`.
`402`	`spend_limit_reached`	The run would pass your organization’s monthly spend limit or the project’s monthly budget. An Owner or Admin can raise them.
`402`	`cost_limit_exceeded`	The quote is higher than the request’s `maxCostMicroUsd`. `details` carries `quotedMicroUsd` and `maxCostMicroUsd`.
`403`	`permission_denied`	The key lacks the endpoint’s scope (`details.scope` names it), the request came from a browser, the API isn’t enabled for your organization, a test key reached outside its sandbox, the owner’s membership doesn’t allow the action, or the model is in early access and not enabled for your organization (the message names the model).
`404`	`not_found`	No such endpoint, or no resource with this ID that the key can reach. An ID that isn’t a UUID is also `not_found`. The message names what’s missing, such as `No project with this ID.`, `No asset with this ID.`, `No folder with this ID.`, or `No label with this ID.`
`409`	`idempotency_conflict`	The `Idempotency-Key` was already used for a different request.
`409`	`idempotency_in_progress`	A request with this `Idempotency-Key` is still running. Retryable.
`409`	`invalid_state`	The run needs a person’s approval, so an API key can’t start it. For example, a run that uses your organization’s own provider key with no provider list price. `details.approvalReason` says why.
`429`	`rate_limited`	A rate limit, a cap on runs in progress, or a URL import limit was reached. Retryable after `Retry-After`. For details, see Rate limits.
`500`	`internal`	Something went wrong in ZeroGen. Retryable.
`503`	`pricing_unavailable`	ZeroGen can’t price the run right now. `retryable` says whether a retry can help.
`503`	`unavailable`	ZeroGen can’t check API keys right now, which is retryable, or your organization’s balance isn’t available, which isn’t.

Validation details

A validation_failed or invalid_request error from schema validation names the first problem in message and param. When the request has more than one problem, details.issues lists up to 10 of them, each with a message and, when it applies, a param:

{
  "error": {
    "code": "validation_failed",
    "message": "Too big: expected number to be <=4",
    "param": "output.count",
    "retryable": false,
    "details": {
      "issues": [
        { "param": "output.count", "message": "Too big: expected number to be <=4" },
        { "param": "output.durationSeconds", "message": "Too small: expected number to be >0" }
      ]
    }
  }
}

Run and output errors

A run’s error and each output’s error use one of the following codes.

Code	Meaning
`provider_error`	The model provider failed, or returned fewer outputs than requested.
`provider_timeout`	The provider didn’t finish in time.
`content_moderation`	The provider refused the request under its content policy.
`input_rejected`	The provider couldn’t use an input, for example because it couldn’t read the file.
`internal`	Something went wrong in ZeroGen.

retryable says whether creating the same run again can succeed. details.reason gives a more specific cause, and details.providerMessage sometimes carries the provider’s own message. Both are for diagnosis: their values can change, so don’t branch on them. For what a failed or cancelled run is charged, see Billing.

​Retry errors

​Request errors

​Validation details

​Run and output errors

Retry errors

Request errors

Validation details

Run and output errors