Errors
Every error response has a stable HTTP status code, a machine-readable code, and a human-readable message.
Error shape
{
"error": {
"type": "invalid_request_error",
"code": "parameter_missing",
"param": "amount",
"message": "The 'amount' parameter is required.",
"doc_url": "https://docs.korvenone.com/errors#parameter_missing",
"request_id": "req_01HT3M9QK7ZS9V0AB"
}
}Status catalog
| Field | Type | Description |
|---|---|---|
400 | invalid_request_error | Missing, malformed, or invalid parameters. |
401 | authentication_error | Missing or invalid API key. |
403 | permission_error | The key is valid but not scoped to this action. |
404 | not_found | Resource does not exist or is not visible to this account. |
409 | conflict | Idempotency-Key reused with different body, or state conflict. |
422 | unprocessable | Business-rule failure (insufficient funds, blocked recipient…). |
429 | rate_limited | Too many requests. Respect Retry-After. |
500 | api_error | Something went wrong on our side. Safe to retry with the same idempotency key. |
503 | service_unavailable | Temporary degradation. Retry with exponential backoff. |
Recovery strategy
- Always log `request_id` — support conversations start there.
- Retry only 429, 500, 502, 503, 504 with exponential backoff (base 500ms, cap 30s, jitter).
- Never retry 400/422 — fix the request first.
- Always send an Idempotency-Key on writes so retries are safe.