Errors & limits

All /v1/* errors use this envelope:

{
  "statusCode": 402,
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient wallet balance: estimated $0.0100 USD, available $0.0000 USD",
    "details": {
      "estimated_usd": "0.010000",
      "available_usd": "0.000000"
    }
  }
}

Field	Description
`statusCode`	HTTP status (same as response status)
`error.code`	Machine-readable code — branch on this in clients
`error.message`	Human-readable explanation
`error.details`	Optional context (balances, limits, `missing_scopes`, validation `issues`)

OpenAI / Gemini SDK routes return vendor-shaped errors. Native REST (/v1/run, /v1/account, etc.) uses the table below.

Error code catalog

Codes below match the live Public API (ApiErrorCode in apisale-service).

`error.code`	HTTP	Thrown when	Client action
`missing_api_key`	401	No `Authorization` header	`Authorization: Key sk-…`
`invalid_api_key`	401	Unknown or revoked key	Create a new key in Console
`forbidden`	403	Suspended account, missing scope, or missing principal	Check scopes (`runs:read`, `runs:write`); see `details.missing_scopes`
`validation_error`	400	DTO / JSON validation failed	Fix body; see `details.issues`
`invalid_media`	400	Bad upload (missing file, MIME, or over size limit)	Fix `POST /v1/media/upload`
`model_not_found`	404	Unknown model slug	Check Explore
`run_not_found`	404	Unknown `run_id`	Use `run_id` from submit response
`insufficient_balance`	402	`wallet.available_usd` too low	Top up
`concurrency_limit_exceeded`	429	Org or key parallel run cap	Backoff; check `GET /v1/account`
`rate_limit_exceeded`	429	Admin-set per-key HTTP cap (default: off)	Backoff or contact support
`content_policy_violation`	451	Safety / moderation block	Revise prompt or media
`invalid_input`	422	Provider rejected input (non-policy)	Fix `input` parameters
`upstream_error`	502	Provider error (4xx/5xx mapped)	Retry later
`service_unavailable`	503	Provider overload or outage	Exponential backoff
`timeout`	504	Run or upstream poll timed out	Retry with longer patience
`internal_error`	500	Unhandled server error	Contact support with `run_id`

Examples

Concurrency (429):

{
  "statusCode": 429,
  "error": {
    "code": "concurrency_limit_exceeded",
    "message": "Organization concurrency limit reached (10/10). Tier=starter.",
    "details": {
      "scope": "organization",
      "limit": 10,
      "in_flight": 10,
      "tier": "starter"
    }
  }
}

Missing scope (403):

{
  "statusCode": 403,
  "error": {
    "code": "forbidden",
    "message": "Missing required API key scopes: runs:write",
    "details": { "missing_scopes": ["runs:write"] }
  }
}

Run failures (HTTP 200)

Failed runs return status: "failed" with:

{
  "run_id": "run_abc",
  "status": "failed",
  "error": {
    "type": "content_policy_violation",
    "code": 451,
    "message": "Request blocked by content safety policy"
  }
}

Field	Meaning
`error.type`	Same string as `error.code` in HTTP errors
`error.code`	HTTP status number for this failure
`error.message`	Customer-safe explanation (vendor/channel internals are not exposed)

error.type uses the same machine-readable strings as error.code in HTTP errors.

Billing outcomes

apisale pre-holds the estimated amount when an accepted run starts. The final charge is created only when the run reaches succeeded / completed.

Run outcome	Wallet result
`succeeded` / `completed`	Charged at the final settled amount
`failed`	No charge; the pre-held amount is released
`timeout`	No charge; the pre-held amount is released
`cancelled`	No charge; the pre-held amount is released
Request rejected before a run is created	No charge

Use the Run history in Console to see the final status and charged amount for each request. A pricing preview is an estimate; the completed run is the source of truth for the final amount.

Concurrency tiers

Parallel runs per organization (by lifetime paid):

Tier	Min. lifetime paid	Concurrent runs
starter	$0	10
growth	$350	25
pro	$1,400	50
scale	$7,000	100

Enterprise overrides are set by apisale admins (concurrency_override).

Response headers

X-Concurrency-Limit: 10
X-Concurrency-In-Flight: 3
X-Concurrency-Remaining: 7

X-RateLimit-* appears only when an admin has set a per-key HTTP cap.

Client recommendations

Branch on error.code, not HTTP status alone (429 = concurrency or optional rate cap)
Poll GET /v1/account before burst traffic
On insufficient_balance (402), pause billing workflows
On content_policy_violation (451), do not blind-retry
Exponential backoff on service_unavailable and concurrency_limit_exceeded

Get Started

Overview

Image

Video

Audio

Model APIs

Official SDK compatibility

Platform API Reference

Errors & limits

Error code catalog

Examples

Run failures (HTTP 200)

Billing outcomes

Concurrency tiers

Response headers

Client recommendations

​Error code catalog

​Examples

​Run failures (HTTP 200)

​Billing outcomes

​Concurrency tiers

​Response headers

​Client recommendations

Error code catalog

Examples

Run failures (HTTP 200)

Billing outcomes

Concurrency tiers

Response headers

Client recommendations