Tuzzle uses standard HTTP status codes with JSON error responses.
{
"message": "The given data was invalid.",
"errors": {
"name": ["The name field is required."],
"space": ["The space field is required."]
}
}
For single errors:
{
"message": "Unauthenticated."
}
{
"error": {
"code": 422,
"message": "Invalid modifiers",
"type": "ValidationError",
"details": { ... }
},
"request_id": "abc123..."
}
| Code | Description |
|---|
| 200 | OK. Request succeeded. |
| 201 | Created. Resource created successfully. |
| 204 | No Content. Request succeeded with no response body. |
| Code | Description |
|---|
| 400 | Bad Request. Malformed request or path traversal attempt. |
| 401 | Unauthenticated. Missing or invalid API key. |
| 403 | Forbidden. Valid auth but insufficient permissions, or invalid signed URL. |
| 404 | Not Found. Resource does not exist. |
| 413 | Payload Too Large. File exceeds the maximum size limit. |
| 422 | Unprocessable Entity. Validation failed (invalid params, format, etc.). |
| 429 | Too Many Requests. Rate limit exceeded. Check Retry-After header. |
| Code | Description |
|---|
| 500 | Internal Server Error. Something went wrong on the server. |
| 503 | Service Unavailable. Server under memory pressure or processing queue full. |
| Error | Cause | Fix |
|---|
| "Unauthenticated." | Missing or invalid API key | Check your API key is correct and active |
| "Forbidden." | Key does not have access to this resource | Verify the key is scoped to the correct space |
| Error | Cause | Fix |
|---|
| "The name has already been taken." | Duplicate space name | Choose a unique name |
| "The file field is required." | Missing file in upload | Include file or files field |
| Error | Cause | Fix |
|---|
| "File type not allowed." | Blocked extension or format not in whitelist | Check upload config's allowed_formats |
| "File too large." | Exceeds max_file_size | Reduce file size or increase config limit |
| "Security validation failed." | Dangerous file extension detected | Upload a safe file type |
| Error | Cause | Fix |
|---|
| "Invalid modifiers" | Bad query parameter values | Check parameter format and ranges |
| "Crop mode requires both width and height" | Missing w or h with r=crop | Provide both dimensions |
| "Format dimension limit exceeded" | WebP/AVIF with >2000px dimension | Use a smaller size or different format |
Validation results are also returned in response headers:
| Header | Content | When |
|---|
x-tzzl-errors | JSON array of errors | On 422 responses |
x-tzzl-warnings | JSON array of warnings | On successful responses with caveats |
For 429 and 503 responses:
- Read the
Retry-After header for the wait time - Wait the specified duration
- Retry the request
- Use exponential backoff if no
Retry-After header is present
For 5xx responses (other than 503):
- Wait 1-2 seconds
- Retry up to 3 times with exponential backoff
- If still failing, check the API status
