SavaPay returns a stable machine-readable code so your server can choose a safe response without relying on message wording.
Error response
Response
{
"success": false,
"code": "idempotency_conflict",
"error": "The idempotency key was used with different request data"
}Log the HTTP status, error code, affected resource, and response correlation ID. Never add API keys, webhook secrets, or customer credentials to your logs.
How to respond
| Code | HTTP | Safe action |
|---|---|---|
invalid_request | 400 | Fix the request. Do not retry unchanged input. |
authentication_required | 401 | Check the server-side API key before retrying. |
forbidden | 403 | Check key permissions and merchant activation. |
not_found | 404 | Confirm the resource ID belongs to this merchant. |
idempotency_conflict | 409 | Do not reuse the key with different request data. |
invalid_state | 409 | Fetch current status before choosing the next action. |
rate_limited | 429 | Wait, then retry with bounded exponential backoff. |
internal_error | 500 | Retry safely; preserve the idempotency key on writes. |
Retry policy
- Retry connection failures, timeouts, rate limits, and temporary server errors.
- Use exponential backoff with a maximum attempt limit.
- Keep the original idempotency key for every retry of a write.
- Add random delay so many workers do not retry at the same moment.
- Do not automatically retry invalid requests, missing resources, or permission errors.
- Reconcile payment status when the final outcome remains uncertain.