OperatePlatform API v1

Errors and recovery

Use the canonical error code, correlation ID, retry metadata, and retained idempotency key to choose one safe next action.

Canonical error shape

JSON

json

{
  "error": {
    "code": "max_cost_exceeded",
    "message": "The current quote exceeds max_cost_usd.",
    "correlation_id": "corr_example",
    "doc_url": "https://autocontentapi.com/developers/errors",
    "details": {}
  }
}

Recovery matrix

HTTP	Representative codes	Action
400	`invalid_request`, option/model/voice/avatar validation codes	Correct the request; do not retry unchanged.
401 / 403	`unauthorized`, `forbidden`	Refresh OAuth or use a key with the required scope.
402	`payment_required`	Add prepaid USD, re-preview, then explicitly retry.
404	`not_found`	Check the account-owned resource ID.
409	`idempotency_conflict`, `idempotency_in_progress`	Reuse the key only with the identical body; poll when directed.
422	`project_not_ready`, Source/input/compatibility errors	Wait for readiness or change the selected resources.
429	`rate_limited`, `provider_operation_limit_exceeded`	Respect `Retry-After` or the authoritative reset.
500 / 502 / 503	`internal_error` or provider availability	Retry only safe reads or the identical keyed mutation.

Ambiguous transport outcomes

If a keyed mutation may have reached the service, do not create a new key. Retry the exact method, path, body, and key or inspect the returned resource when available. Never automatically replay a consumed one-shot upload stream.