Errors & retries
v2 status codes
| Status | Meaning | Retry? |
|---|---|---|
| 200 | Request processed. Check detection. |
— |
| 400 | Image couldn't be used (invalid_image). |
No. Fix the image. |
| 401 | Missing or invalid API key ID or secret access key (unauthorized). |
No. Fix the credentials. |
| 404 | Unknown model (model_not_found) or path. |
No. |
| 405 | Wrong HTTP method (method_not_allowed). |
No. |
| 413 | Request body larger than 10 MB (http_error). |
No. Send a smaller image. |
| 422 | Request body failed validation (invalid_request). |
No. Fix the request. |
| 500 | Unexpected server error (internal_error). |
Yes, with backoff (a small number of times). |
| 502 | The prediction service is temporarily unavailable (upstream_unavailable). |
Yes, with exponential backoff. |
| 429 / 503 / 504 | Returned by the hosting platform during overload, deploys, or timeouts. The body may not be JSON. | Yes, with exponential backoff. |
Recommended retry policy
- Retry only 429, 500, 502, 503, and 504, and network errors or timeouts.
- Use exponential backoff with jitter (for example 1 s, 2 s, 4 s), at most 3 attempts.
- Retrying is safe: only successful predictions are recorded, and a retry returns a fresh result. If your client times out after the server has already finished, the retry is recorded as a second prediction with its own
scan_id. - Parse error bodies defensively: if the body isn't JSON, fall back to the HTTP status.
import random
import time
import requests
RETRYABLE = {429, 500, 502, 503, 504}
BASE_URL = "https://tably-admin.sylvester.ai"
def predict(image_b64, api_key_id, secret_access_key, request_id=None, attempts=3):
headers = {
"tably-api-key-id": api_key_id,
"tably-secret-access-key": secret_access_key,
}
if request_id:
headers["X-Request-ID"] = request_id
for attempt in range(attempts):
try:
r = requests.post(f"{BASE_URL}/api/v2/predict", headers=headers,
json={"image": image_b64}, timeout=60)
except requests.RequestException:
if attempt == attempts - 1:
raise
else:
if r.status_code not in RETRYABLE or attempt == attempts - 1:
return r
time.sleep((2 ** attempt) + random.random())
For v1 error behaviour, see API v1 errors.