Skip to content

Common errors

Jump to bottom
Pim Feltkamp edited this page Apr 28, 2026 · 1 revision

Common errors

Every Cryptohopper SDK surfaces errors with the same code taxonomy. Here's what each one actually means in practice and how to debug it.

code HTTP Meaning Most-common cause
UNAUTHORIZED 401 Token invalid / missing Token expired, never issued, or pasted wrong (try cryptohopper whoami)
FORBIDDEN 403 Token valid but not permitted OAuth app has IP allowlist that doesn't include your current IP — error includes ip_address field
DEVICE_UNAUTHORIZED 402 Mobile device flow only Public SDK users won't see this
NOT_FOUND 404 Resource or endpoint gone Wrong ID, hopper deleted, or endpoint typo
VALIDATION_ERROR 400 / 422 Bad parameters Missing required field, wrong type, value out of range
CONFLICT 409 State conflict Trying to create something that already exists, or operate on a hopper in the wrong state
RATE_LIMITED 429 Too many requests SDK auto-retries with Retry-After; only surfaces after maxRetries
SERVER_ERROR 500/502/504 Upstream blip Retry; if persistent check status page
SERVICE_UNAVAILABLE 503 Maintenance window Try again in a few minutes
NETWORK_ERROR — Couldn't reach the server DNS, firewall, corporate proxy blocking, TLS handshake failure
TIMEOUT — Request exceeded total deadline Slow network or backend; tighten/relax timeout per workload
UNKNOWN — Catch-all Should be rare; report if you see one

Debugging recipes

UNAUTHORIZED on every call

cryptohopper whoami --json

If this returns ok, the token is valid — your code is doing something different (different env var? wrong header? trimming the token?). If this returns UNAUTHORIZED too, the token is bad. cryptohopper login to reissue, or check the developer dashboard.

FORBIDDEN with an IP address

{"code": "FORBIDDEN", "ip_address": "203.0.113.42"}

Means the server saw your request from 203.0.113.42 and that IP isn't on your OAuth app's allowlist. Either add it (developer dashboard → OAuth apps → IP allowlist) or disable the allowlist for that app.

VALIDATION_ERROR from a request that looks correct

The error message contains the exact field. Common gotchas:

  • Date fields want YYYY-MM-DD strings, not Date objects.
  • Boolean flags want 0/1 integers, not true/false.
  • hopper_id must be a number/string the server recognizes — check cryptohopper hoppers list to confirm it exists.

RATE_LIMITED despite low traffic

You're sharing the rate-limit bucket with other unattributed callers using your token. Pass appKey (your OAuth client_id) to the SDK constructor — that gets you a separate per-app bucket.

NETWORK_ERROR only from CI

Corporate proxies often strip the access-token header (they think it looks like sensitive data). Either configure the proxy to pass it through, or use HTTPS_PROXY env var so the SDK sees the proxy and Trust-its-egress.

TIMEOUT on backtest polling

The backtest itself takes minutes. The poll calls (backtest.get) should be fast. If backtest.get itself times out, your network is the problem, not the backtest.

"Missing Authentication Token" in the message

This is the AWS API Gateway rejecting your Authorization: Bearer header. Switch to access-token. See Auth-header-gotcha.

Forward compatibility

If the server adds a new error code, the SDK passes it through verbatim on code. Compare with ==, never substring-match. The KNOWN_CODES set on each SDK enumerates what the SDK currently emits — anything outside that set is forward-compatibility.

See also

Pages

Repository

SDK suite

Clone this wiki locally