409 avatar_handle_taken, and how a failed avatar frees its handle
avatar_handle_taken means the handle is in use. When an avatar creation fails at reservation, the old handle is renamed so you can reuse it. Code-verified.
When you get avatar_handle_taken
POST /v1/avatar-1.0/generate checks whether your workspace and owner already have an avatar with that handle. If one exists, the API marks the new creation job failed with code avatar_handle_taken and answers 409. The details include handle and, on the lookup path, the avatar_id of the avatar that holds it.
A race can reach the same error: if two creates insert the same handle at once, the database rejects the second on a unique violation, and the API reports avatar_handle_taken for it as well.
What a failed creation does to the handle
If an avatar record was created but the job then fails at reservation, for example from a credit reservation error or 429 queue_full, the API marks the avatar failed and releases the handle. The released handle is renamed to the first 17 characters of the old handle, then _failed_, then the last 8 characters of the avatar id.
That rename frees the clean handle for your next attempt. You do not need to delete anything.
| Situation | HTTP result | Can you reuse the handle? |
|---|---|---|
| Another avatar already holds it | 409 avatar_handle_taken | No, pick another |
| Creation failed at reservation | Error such as 429 queue_full | Yes, the handle is released |
| Avatar is processing or ready | Handle held | No |
A safe retry pattern
- On 429 queue_full, wait and resend with the same Idempotency-Key and the same handle.
- On 409 avatar_handle_taken, read the avatar_id in details first. It may be your own earlier avatar, which you can use as is.
- Never resend a changed body under an old Idempotency-Key; that is a different 409.
Sources
Related posts
More in Developers
- Avatar photo 400 unsupported_image_type: PNG, JPEG, WebP, GIF only
Sume's avatar photo preflight accepts four image content types. An HTML page, AVIF or HEIC answer returns 400 unsupported_image_type and no job is created.
- Avatar photo 413 image_too_large: 16,384 px and 100 MP limits
A Sume avatar photo over 16,384 px on a side, or over 100,000,000 pixels, returns 413 image_too_large before any job exists. Downscale it first.
- Avatar photo image_not_fetchable: 404, timeouts and the 15 s limit
Sume gives an avatar photo host 15 seconds for fetch and body read. A non-2xx status or a timeout returns 400 image_not_fetchable. How to fix it.
- Avatar photo 400 invalid_image: under 64 px or a 6:1 aspect ratio
Sume rejects an avatar photo that is not decodable, is under 64 px on a side, or is more than 6:1. The 400 invalid_image error reports width, height and reason.
Written by Sume