Errors
Standard error codes and responses from the Price Hero API.
All Price Hero API errors return a consistent JSON response with an error code and a human-readable message.
Error response format
{
"error": "error_code",
"message": "A description of what went wrong."
}HTTP status codes
| Status | Error code | Meaning |
|---|---|---|
400 | bad_request | Missing or invalid request body / parameters |
401 | unauthorized | Missing, invalid, or revoked API key |
402 | insufficient_credits | Not enough credits to complete the request |
404 | not_found | Requested resource (e.g. catalog item) does not exist |
413 | payload_too_large | Image or request body exceeds size limit |
422 | unprocessable | Request was understood but couldn't be processed (e.g. unreadable image) |
429 | rate_limited | Too many requests — back off and retry |
500 | internal_error | Something went wrong on our end |
Retrying requests
We recommend exponential backoff for 429 and 5xx errors:
async function requestWithRetry(url: string, options: RequestInit, retries = 3) {
for (let i = 0; i < retries; i++) {
const res = await fetch(url, options);
if (res.status !== 429 && res.status < 500) return res;
await new Promise((r) => setTimeout(r, Math.pow(2, i) * 200));
}
throw new Error("Max retries exceeded");
}Common issues
401 unauthorized — Double-check that your key is correct and hasn't been revoked. Make sure you're sending the Authorization: Bearer <key> header.
402 insufficient_credits — Top up your balance in the Developer Dashboard.
422 unprocessable on vision — The image couldn't be analyzed. Ensure the image is clear, well-lit, and shows the item distinctly. Supported formats: JPEG, PNG, WebP.