Kraken Error Recovery
Apps & Automationkraken-error-recoveryKraken Error Recovery is an Agent Skill for apps & automation published in the krakenfx/kraken-cli repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Handle order failures, network errors, and duplicate submissions safely.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/krakenfx/kraken-cli/blob/HEAD/skills/kraken-error-recovery/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/kraken-error-recovery, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
kraken-error-recovery
Use this skill for:
- recovering from failed order submissions
- preventing duplicate orders after network errors
- handling partial fills and stuck states
- building resilient agent loops
Error Categories
Parse the .error field from the JSON response:
| Category | Meaning | Recovery |
|---|---|---|
auth | Credentials invalid or expired | Re-authenticate, do not retry |
rate_limit | Too many requests | Read suggestion and docs_url fields, adapt strategy |
network | Connection failed | Retry with exponential backoff |
validation | Invalid request parameters | Fix inputs, do not retry unchanged |
api | Exchange-side rejection | Inspect error message, adjust request |
Duplicate Order Prevention
After a network error during order submission, the order may or may not have reached the exchange. Check before resubmitting:
kraken open-orders -o json 2>/dev/null
If the order appears in open-orders, do not resubmit. If absent:
kraken trades-history -o json 2>/dev/null
If the order filled immediately, it appears in trades. Only resubmit if the order is absent from both.
Client Order ID for Idempotency
Use --cl-ord-id to tag orders with a unique identifier:
kraken order buy BTCUSD 0.001 --type limit --price 50000 --cl-ord-id "dca-2024-01-15-001" -o json 2>/dev/null
If the submission fails, query by client order ID to check if it reached the exchange:
kraken open-orders --cl-ord-id "dca-2024-01-15-001" -o json 2>/dev/null
Cancel by client order ID if needed:
kraken order cancel --cl-ord-id "dca-2024-01-15-001" -o json 2>/dev/null
Network Error Recovery Pattern
1. Submit order (capture exit code and response)
2. If exit code != 0 and error == "network":
a. Wait 2 seconds
b. Check open-orders for the order (by cl-ord-id or recent orders)
c. If found → order succeeded, proceed
d. If not found → check trades-history
e. If in trades → order filled, proceed
f. If absent from both → safe to retry
3. Retry with same cl-ord-id
Rate Limit Recovery
The CLI returns rate limit errors immediately with no internal retry. The error includes actionable fields for the agent to decide next steps.
On rate_limit error:
- Read the
suggestionfield for specific guidance on what limit was hit and how to adapt. - Read the
docs_urlfield for the relevant Kraken documentation. - Decide whether to retry (and when), reduce request frequency, or switch to WebSocket streaming for real-time data.
- Resume with a single test call before continuing the loop.
# { "error": "rate_limit", "suggestion": "...", "docs_url": "...", "retryable": true }
kraken status -o json 2>/dev/null
If status succeeds, the rate limit has cleared.
Partial Fill Handling
Limit orders may partially fill. Check order status:
kraken query-orders <TXID> -o json 2>/dev/null
Fields: vol (requested volume), vol_exec (filled volume), status (open, closed, canceled).
If partially filled and the remaining volume is needed, amend or place a new order for the remaining amount.
Stuck Order Resolution
An order stuck in open state that should have filled or been canceled:
- Check the order:
kraken query-orders <TXID> -o json 2>/dev/null - If still open, cancel:
kraken order cancel <TXID> -o json 2>/dev/null - Verify cancellation:
kraken open-orders -o json 2>/dev/null
Hard Rules
- Never blind-retry an order after a network error; always check state first.
- Use
--cl-ord-idfor all orders in automated loops. - On auth errors, stop all activity and re-authenticate.
- Log every error and recovery action for post-session audit.