Error Codes Reference
Complete reference for all error responses from the Setara API.
Error Response Format
All error responses follow a consistent JSON shape regardless of the HTTP status code:
json
{
"error": "error_code",
"message": "Human readable message"
}Use the error field for programmatic handling. Use the message field for display or logging.
All Error Codes
| HTTP Status | Error Code | Description | Resolution |
|---|---|---|---|
| 400 | missing_fields | Required fields are missing from the request | Check the API reference for required fields |
| 400 | invalid_hash | Hash format is invalid (must be sha256:...) | Prefix your SHA-256 hash with "sha256:" |
| 400 | invalid_email | Email format is invalid | Provide a valid email address |
| 401 | unauthorized | Missing or invalid API key | Include X-API-Key header with your sk_ key |
| 402 | insufficient_credits | Organization has no remaining credits | Top up credits via admin or contact sales |
| 404 | not_found | Resource not found | Verify the endpoint URL and parameters |
| 409 | already_registered | Email or document hash already exists | Check for duplicate registrations |
| 429 | rate_limited | Too many requests | Wait and retry with exponential backoff |
| 500 | chain_error | Blockchain transaction failed | Retry after 5 seconds; if persistent, check node status |
| 500 | internal_error | Unexpected server error | Report to support@setara.network |
Retry Strategy
For 429 rate_limited and 500 errors, use exponential backoff: wait before retrying, and double the wait time on each subsequent failure.
javascript
async function withRetry(fn, maxAttempts = 4) {
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
try {
const res = await fn();
if (res.status === 429 || res.status >= 500) {
const wait = Math.min(1000 * 2 ** (attempt - 1), 16000); // 1s, 2s, 4s, 8s, 16s cap
if (attempt < maxAttempts) {
await new Promise((r) => setTimeout(r, wait));
continue;
}
}
return res;
} catch (err) {
if (attempt === maxAttempts) throw err;
}
}
}- 429 rate_limited: back off and retry — the request is valid but throttled
- 500 chain_error: retry after at least 5 seconds; the blockchain node may be catching up
- 500 internal_error: retry once; if the error persists, contact support
- 4xx client errors: do not retry — fix the request first
Getting Help
If you encounter an error not listed here, or a persistent 500 internal_error, please reach out: