Error Handling & Retry Logic

Overview

When integrating spritesynth into your pipeline, you'll encounter transient failures: a generation node is busy, you hit a rate limit, or your credits run dry. Building robust error handling ensures your pipeline recovers automatically instead of dropping assets on the floor.

Step 1: Poll Generation Status

After submitting a generation, poll its status to detect failures:

curl https://api.spritesynth.com/v1/generations/{generation_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

The response includes:

• status — pending, processing, completed, or failed
• error_message — human-readable failure reason (only when failed)
• credits_cost — deducted credits (refunded on failure)

Poll every 5 seconds for fast models, 15 seconds for SDXL. Implement exponential backoff (5s, 10s, 20s, 30s) to avoid hammering the API.

Step 2: Retry a Failed Generation

If a generation fails (e.g., RunPod timeout), retry with the exact same parameters:

curl -X POST https://api.spritesynth.com/v1/generations/{generation_id}/retry \
  -H "Authorization: Bearer YOUR_API_KEY"

Failed generations are automatically refunded, so retrying doesn't double-charge. The new generation gets a fresh generation_id.

Step 3: Cancel a Stuck Job

If a generation stays processing for too long (e.g., >10 minutes for fast, >20 for SDXL), cancel it:

curl -X POST https://api.spritesynth.com/v1/generations/{generation_id}/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

Cancellation refunds credits and frees the generation slot. After cancelling, you can resubmit with a new request.

Step 4: Handle HTTP Errors

curl -X POST https://api.spritesynth.com/v1/generations/image \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
"prompt": "pixel art sprite, knight"
  }'
# HTTP 402 — check credits and notify user
# HTTP 429 — parse Retry-After header, sleep, retry

Tips

• Idempotency keys — Include an idempotency_key in your requests to safely retry without duplicate generations.
• Log error messages — Always log error_message from failed generations to debug prompt or model issues.
• Monitor your queue — If you see repeated failures, check your prompt for problematic keywords or reduce batch concurrency.
• Webhook alternative — Instead of polling, set up a webhook endpoint and spritesynth will POST completion events to it.