Skip to content
APIonWeb

Developer Docs

Errors

Browse documentation

Every API error — regardless of cause — is returned with the correct HTTP status code and the same JSON envelope, so you can write one error handler for the whole API:

Error envelope 
{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient API balance. Please recharge your APIonWeb account."
  }
}

error.code is a stable, machine-readable string safe to branch on in code. error.message is human-readable and may change wording over time — don't parse it.

Error codes

Code HTTP status Description
invalid_api_key 401 The API key is malformed, unknown, or has been revoked.
authentication_required 401 No Authorization header was included on the request.
insufficient_balance 402 Your account balance is too low to cover this request's cost.
invalid_request 422 The request body failed validation — a required field is missing or malformed.
invalid_image 422 A provided image URL is unreachable, unsupported, or not a valid image.
invalid_model 422 A provided 3D product model URL is unreachable or malformed.
unsupported_category 422 The category value isn't one APIonWeb currently supports.
processing_failed 422 The try-on could not be generated from the provided inputs.
rate_limit_exceeded 429 You've exceeded the per-endpoint rate limit for your account.
not_found 404 The request_id doesn't exist, or doesn't belong to your account.
internal_error 500 An unexpected error occurred on APIonWeb's side — safe to retry.

Retryable

rate_limit_exceeded and internal_error are typically transient — retry with backoff.

Not retryable as-is

4xx validation and auth errors won't succeed on retry until you fix the underlying request, key, or balance.

Infrastructure failures and requests rejected for insufficient balance are never charged — only a successful result is billed. See Usage & Billing.