AutoSprite API Errors, Rate Limits & Credit Costs

Reference for AutoSprite REST API error codes, plan requirements, rate limits, credit costs, and pagination.

How the REST API behaves once you're calling it: error codes, plan gating, rate limits, credit costs, and pagination. New to the API? Start with the API hub or the Quick Start.

Error Handling

All errors return a consistent JSON structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Error Codes

Code	Status	Description
`UNAUTHORIZED`	401	Missing or invalid API key
`PLAN_REQUIRED`	403	Paid subscription required — generation endpoints are gated to paid plans
`RATE_LIMIT_EXCEEDED`	429	Too many requests — check `Retry-After` header
`INSUFFICIENT_CREDITS`	402	Not enough credits for this operation
`DUPLICATE_CHARACTER`	409	A character with this name already exists
`DUPLICATE_ASSET`	409	An asset with this name already exists
`FOLDER_NOT_FOUND`	404	Asset folder not found or access denied
`NOT_FOUND`	404	Resource not found or not owned by you
`MISSING_ANIMATIONS`	400	No animations provided
`TOO_MANY_ANIMATIONS`	400	Maximum 10 animations per request
`MISSING_PROMPT`	400	Custom animations require a prompt
`MISSING_ANIMATION_ID`	400	Redo request missing `animationId`
`ANIMATION_NOT_FOUND`	404	Animation hasn't been generated yet
`MODEL_REQUIRED`	400	3D animation requested but the character has no 3D model yet
`INVALID_ANIMATIONS`	400	One or more 3D animation ids aren't in the catalog
`MISSING_BASE_IMAGE`	400	Character has no base image to build a 3D model from
`JOB_IN_FLIGHT`	409	A 3D job is already running for this character
`INTERNAL_ERROR`	500	Something went wrong on our end

Access & Plan Requirements

All endpoints require a valid API key. Generation and write endpoints (POST/DELETE) additionally require an active subscription plan. Read-only endpoints are available to all authenticated users.

Access Level	Endpoints
Any authenticated user	List characters, list assets, get character, list/get spritesheets, list/get jobs, list poses, get 3D model state, check account balance
Paid plan required	Create/delete characters, create assets, generate animations and isometric packs, redo animations, generate poses, pad characters, regenerate spritesheets, build 3D models, unlock 3D animations

Free-tier users calling a paid endpoint will receive a 403 PLAN_REQUIRED error.

Rate Limits

API requests are rate limited per user. Read requests (GET/HEAD — status polling, listing, downloads) and write requests (POST/DELETE — generation, creation) are budgeted separately, so polling a job or downloading your spritesheets never eats into your generation budget.

Limit	Value	Applies to
Burst	120 requests / minute	All requests
Daily writes	3,000, refilling 125/hour	Everything except GET/HEAD (POST, DELETE, …)
Daily reads	20,000, refilling 834/hour	GET and HEAD requests

Daily budgets are token buckets: you can spend the full budget in a single burst, and capacity refills at the hourly rate around the clock — there is no fixed reset time, and after a daily-limit 429 the Retry-After header is at most an hour away.

If you hit a limit, you'll receive a 429 response with a Retry-After header indicating when you can retry. Tips for staying under:

Poll job status every 5–10 seconds rather than in a tight loop, and stop polling once a job reaches succeeded or failed.
Batch reads with list endpoints instead of fetching items one at a time.

Running an automated pipeline that needs more headroom? Contact us — higher limits are available for high-volume accounts.

Credits

Most generation operations cost credits. Credits are reserved before processing starts and automatically refunded if an operation fails.

Operation	Credits
Create character (from prompt, turbo)	1
Create character (from prompt, pro)	3
Create character (upload image)	Free
Create asset (from prompt, turbo or ultra)	1
Create asset (upload image)	Free
Generate animation	5 per animation
Generate animation with sound	10 per animation
Generate pose	5
Pad character	1 (free if size = 100)
Build 3D model (rigged GLB + idle)	50
Add 3D animation clip	5 per clip
Redo animation	Free (plan allowance) or 5 per redo
Redo animation with sound	Free (plan allowance) or 10 per redo
Regenerate spritesheet	Free

Check your balance anytime:

curl https://www.autosprite.io/api/v1/account \
  -H "x-api-key: vspk_your_key_here"

{
  "credits": 150
}

Pagination

List endpoints use cursor-based pagination:

# First page
GET /api/v1/characters?limit=20

# Next page (use nextCursor from previous response)
GET /api/v1/characters?limit=20&cursor=abc123

limit — Items per page (1–50, default 20)
cursor — Cursor from the previous response's nextCursor

What's Next?

Follow the Quick Start for a full end-to-end walkthrough, or jump into the endpoint reference:

👤

Characters API

Create, list, and manage characters

🗡️

Assets API

Create and list game assets (props, weapons, items)

🎬

Spritesheets API

Generate animations and isometric 8-direction packs, export spritesheets

🎯

Poses API

Generate custom poses for first/last frames

⚡

Jobs API

Track generation progress and poll for results

Errors, Limits & Credits