Spatius API Errors and Limits

Error envelope

Every Spatius API error returns the same JSON envelope, regardless of which endpoint failed:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Open API rate limit exceeded",
    "requestId": "b3f0c2d1-4a5b-4c6d-8e9f-0a1b2c3d4e5f"
  }
}

code is a stable machine-readable string. Program against code, not message.
message is a human-readable explanation specific to this occurrence.
requestId uniquely identifies the request. It is also returned in the X-Request-ID response header. Quote it when contacting support.

HTTP status and error code mapping

HTTP status	`code`	Meaning
`400`	`invalid_request`	Malformed request: missing `imageUrl`, an invalid ID in the path, a page token that is invalid or does not match `pageSize`, or no active avatar pipeline configured.
`401`	`unauthorized`	Missing or mismatched `X-App-ID` / `X-API-Key` pair. See Authentication.
`402`	`insufficient_avatar_units`	The account has no Avatar Creations left. View your balance at app.spatius.ai/avatars/creations.
`403`	`forbidden`	API access is not configured (`Open API access is not configured`), or avatar creation is disabled for the account (`API Avatar creation is disabled`).
`404`	`not_found`	The avatar or job does not exist, or belongs to another account.
`429`	`rate_limit_exceeded`	A rate limit or the rolling 24-hour creation quota was exceeded.
`429`	`concurrency_limit_exceeded`	Too many jobs are queued or processing at once. Wait for an active job to finish.
`500`	`internal_error`	An unexpected server error. Retry with backoff; quote `requestId` if it persists.
`501`	`unsupported_input`	The request uses an input that this API version does not support yet.
`503`	`service_unavailable`	A transient backend failure, for example reservation contention. Retry the request.

Job failure codes

When a creation job reaches failed, the job’s error object carries one of these codes:

Code	Message	Meaning
`source_download_failed`	`The source image could not be downloaded.`	The image URL could not be fetched or stored. Host the image on fast, reliable storage and resubmit.
`invalid_image`	`The source image is not a supported opaque JPEG or PNG of sufficient size.`	The file is not a valid JPEG or PNG, exceeds 5 MiB, is smaller than 340 px on its shorter side, or is a non-opaque PNG. Fix the image and resubmit.
`image_quality_rejected`	`The source image did not pass Avatar image requirements.`	The image passed format validation but was rejected by content checks, for example because it does not contain exactly one clearly visible face.
`preprocess_failed`	`The source image could not be preprocessed.`	Preprocessing failed after download. Retry; contact support if it persists.
`avatar_generation_failed`	`Avatar generation failed.`	Avatar generation failed or could not be started. Retry; contact support if it persists.
`internal_error`	—	An unexpected failure. Retry; quote the job ID when contacting support.

The retryable flag on the error indicates whether resubmitting the same request may succeed.

Rate limits

Limits are enforced per account. Your account may be configured below these hard caps:

Limit	Hard cap
Avatar creations per minute	20
Avatar creations per hour	200
Avatar creations per rolling 24 hours	2,000
Concurrent active creation jobs	10
Read requests per second (token bucket)	20, burst 40
Read requests per minute	1,200

Read limits apply to the GET endpoints; creation limits apply to POST /avatars. When a limit is hit, the API returns 429 with rate_limit_exceeded (or concurrency_limit_exceeded when the concurrency cap is the binding constraint). Back off and retry — for job polling, an interval of 5–10 seconds stays comfortably within the read limits.

Pagination

Both list endpoints (GET /avatars and GET /avatar-jobs) paginate the same way. They accept pagination.pageSize and pagination.pageToken, and return pagination.nextPageToken and pagination.totalCount. pageSize defaults to 20 and has a maximum of 99.

A pageSize above 99 does not return 99 items — it falls back to the default of 20. Request at most 99 to avoid receiving fewer items than you expect.

To page through results, pass the previous response’s pagination.nextPageToken as pagination.pageToken. An empty nextPageToken means there are no more pages. Treat the token as opaque and pass back exactly what you received; do not construct or increment it yourself. An invalid page token is rejected with 400 and invalid_request.

Keep pageSize the same for every request in a pagination sequence. A token is only valid for the pageSize it was issued with, and reusing it with a different pageSize is rejected with 400 and invalid_request. To change the page size, start again from the first page with no pageToken.

Start Here

Avatar API

Spatius API Errors and Limits

Error envelope

HTTP status and error code mapping

Job failure codes

Rate limits

Next steps

Overview

Authentication

​Error envelope

​HTTP status and error code mapping

​Job failure codes

​Rate limits

​Pagination

​Next steps

Overview

Authentication

Error envelope

HTTP status and error code mapping

Job failure codes

Rate limits

Pagination

Next steps