Authentication & Errors
Public reads need nothing. Anything that touches your account or moves $USDI uses an API key. Failures are classified by HTTP status, which is stable and easy to switch on.
API keys
Send your key in the X-Inkle-Api-Key header:
bash
curl https://api.inklemarket.com/v1/user/me \ -H "X-Inkle-Api-Key: ik_live_xxx"
Keys look like ik_live_<lookup>_<secret>. Only a SHA-256 hash is stored server-side, so Inkle can never show you the raw key again. Treat it like a password.
Scopes
read: market data plus your own account and positions (theGETroutes).trade: create markets and place or close positions on the USDI rail. A key without this scope gets a403on trading calls.
Error codes
Every failure returns the envelope with a non-2xx HTTP status:
json
{ "status": "FAIL", "errorCode": "…", "error": "invalid API key" }The error field is a human-readable message. Match on the HTTP status, which the SDK exposes as a stable type:
| HTTP | SDK type | Meaning | Retry? |
|---|---|---|---|
| 400 | invalid_request_error | Bad parameters or a rejected business rule (for example insufficient $USDI). | No |
| 401 | authentication_error | Missing, invalid, or revoked API key. | No |
| 403 | permission_error | The key is valid but lacks the required scope. | No |
| 404 | not_found | The market or resource does not exist. | No |
| 429 | rate_limit_error | Too many requests. Back off and retry. | Yes |
| 500+ | api_error | Server-side fault. Safe to retry. | Yes |
| n/a | connection_error | Network failure with no HTTP response. | Yes |
| n/a | timeout_error | The request exceeded the client timeout. | Yes |
The SDK retries the last four automatically with exponential backoff. See the SDK guide for how to catch and branch on these.
Security
- Keep keys server-side. Never ship them in a browser bundle.
- Use a read-only key wherever you only need data.
- Revoke a key the moment it might be exposed. Revocation takes effect immediately.
- Up to 5 active keys per account.