API Errors
When communicating with exchanges, various API errors can occur. This guide explains common error codes and how to resolve them.
HTTP Status Codes
401 — Unauthorized
Meaning: Your API credentials are invalid or expired.
Common causes:
- API key was deleted on the exchange
- API key expired (some exchanges have expiration dates)
- Secret key or passphrase is incorrect
- System clock is significantly out of sync
Solution:
- Verify the API key exists on your exchange
- Create a new API key if needed
- Update credentials in Settings → API Keys
403 — Forbidden
Meaning: Your API key doesn't have permission for the requested action.
Common causes:
- Missing trade permission when trying to place orders
- IP restriction blocking the request
- Account-level restrictions on the exchange
Solution:
- Check API key permissions on your exchange
- Verify IP whitelist settings (if any)
- Check for any account restrictions
429 — Rate Limited
Meaning: Too many requests sent to the exchange API.
Common causes:
- Multiple applications using the same API key
- Rapid manual refreshing
- Temporary spike in API calls
Solution:
- Wait 60 seconds before retrying
- Avoid rapid manual refreshing
- Use a dedicated API key for Crodl
Crodl does not silently retry a rate-limited request behind your back — a 429 surfaces so you can see it happened. The one place Crodl backs off automatically is chart layout autosave, which honours the Retry-After header before trying again. Everywhere else, wait and repeat the action yourself.
500+ — Server Error
Meaning: The exchange is experiencing internal issues.
Common causes:
- Exchange maintenance
- High load on the exchange
- Temporary outage
Solution:
- Wait and retry — these are usually temporary
- Check the exchange's status page
- Crodl surfaces the error and recovers on the next refresh cycle — server errors are not blindly retried
Crodl Trade Guard Errors
These errors happen inside Crodl before the order is submitted to the exchange.
| Error Code | Meaning | Solution |
|---|---|---|
max_notional_breached | The open trigger's final computed position notional exceeded max_notional_usd and guard_action was reject | Increase max_notional_usd, reduce quantity_amount, or use guard_action: "clamp" |
max_notional_clamp_below_min_size | Crodl tried to clamp the order to max_notional_usd, but the resulting size was below the exchange minimum order size | Increase max_notional_usd or send a larger valid order size |
Trade guard errors only apply when an open trigger includes max_notional_usd. If the guard fields are omitted, Crodl does not enforce a notional cap.
Exchange-Specific Errors
Blofin
| Error Code | Meaning | Solution |
|---|---|---|
| 50001 | Invalid parameter | Check order parameters |
| 50004 | API key suspended | Reactivate on Blofin |
| 51008 | Insufficient margin | Add funds or reduce size |
Bybit
| Error Code | Meaning | Solution |
|---|---|---|
| 10003 | Invalid API key | Regenerate key |
| 10005 | Permission denied | Check key permissions |
| 110007 | Insufficient balance | Add funds |
Bitget
| Error Code | Meaning | Solution |
|---|---|---|
| 40014 | Invalid API key | Regenerate key |
| 40015 | Invalid passphrase | Re-enter passphrase |
| 43011 | Insufficient margin | Add funds |
OKX
| Error Code | Meaning | Solution |
|---|---|---|
| 50011 | Rate limit exceeded | Wait and retry; reduce rapid refreshes |
| 50113 | Invalid signature or credentials | Re-check API key, secret, and passphrase |
| 51008 | Insufficient margin | Add funds or reduce size |
Bitunix
| Error Code | Meaning | Solution |
|---|---|---|
| 1001 | Invalid parameter | Check request format |
| 1002 | Authentication failed | Verify credentials |
Hyperliquid
Hyperliquid returns plain-text error messages rather than numeric error codes. Common ones relate to an unknown or mistyped wallet address and insufficient collateral for the requested order — check your Master/Agent addresses in Settings → API Keys and your deposited margin on Hyperliquid.
Error Handling in Crodl
Crodl handles API errors automatically:
- Session recovery — a 401 refreshes your session and retries the request once, so an expired token does not surface as an error
- In-flight deduplication — prevents duplicate requests
- Granular error messages — specific messages for each error type
- Abort on unmount — prevents stale requests from affecting the UI
- Layout autosave backoff — chart layout saves respect
Retry-Afteron a 429 instead of hot-looping
If you see persistent errors across multiple refreshes, the issue is likely with your API key configuration. Try removing and re-adding your exchange connection.