Getting Started
Errors and retries
Handle Yuzu API failures safely.
Errors and retries
Yuzu uses standard HTTP status codes. Error bodies include a message or validation details when available.
Status codes
| Status | What to do |
|---|---|
400 | Fix the request body or query parameters. Do not retry unchanged. |
401 | Check the X-API-Key header and key status. |
403 | Check that the key belongs to the expected team. |
404 | Check the order ID, order key, printer, or template reference. |
429 | Retry with exponential backoff and jitter. |
5xx | Retry with backoff. Contact Yuzu if it continues. |
Retry safely
Create-order retries are safe when you reuse the same source and sourceId. Yuzu uses those values as the order identity, so a repeated request updates the existing order instead of creating a duplicate.
For print requests, retry only when you did not receive a response or received 429 or 5xx. If a print request returns 200, inspect the response array: individual batches can still have warning or error statuses.
Backoff example
async function requestWithRetry(url: string, options: RequestInit) {
for (let attempt = 0; attempt < 4; attempt++) {
const response = await fetch(url, options)
if (![429, 500, 502, 503, 504].includes(response.status)) return response
const delayMs = (2 ** attempt) * 1000 + Math.random() * 500
await new Promise(resolve => setTimeout(resolve, delayMs))
}
throw new Error('Yuzu request failed after retries')
}