The codes#
| Code | HTTP | Charged | What happened | What to do |
|---|---|---|---|---|
Budget_Exhausted | 402 | No | The wallet cannot cover this call, or the key's rolling 24-hour cap would be exceeded. Both are reported the same way, deliberately: either way you have hit a ceiling you set. | Read X-Nexus-Required-Amount for the shortfall, then add funds or raise that key's cap. |
Rate_Limited | 429 | No | Too many requests for this key inside its window. | Honour Retry-After. Retrying sooner meets the same window and wastes the attempt. |
Upstream_Unavailable | 502 | Usually not | The creator's endpoint failed, timed out before its first byte, or answered in a shape we refuse to relay — including a redirect, which we never follow. | Retry. You are refunded automatically if the failure happened before any of the response reached you; if it failed mid-stream, the charge stands. |
Lock_Unavailable | 503 | No | Our own infrastructure could not authorize the call, so we failed closed rather than guess. A metering system that cannot read its own state must refuse, not assume. | Retry with backoff. A 503 is never a silent debit. |
Idempotency_Conflict | 422 | No | This Idempotency-Key was already used for a DIFFERENT request. A duplicate of the same request returns the original result for free; a different one is refused rather than replayed. | Use a fresh key for a different request. |
Authorization_Rejected | 400 | No | Your pass-through Authorization header carried an nx_dev_ token, which would have handed your Nexus key to a creator who could then spend your wallet. | Put the tool's own credential there, never your Nexus key. |
The shape of a refusal#
Every refusal carries the code in both a header and the body, so you can branch on it without parsing JSON if you would rather not.
HTTP/1.1 402 Payment Required
X-Nexus-Error: Budget_Exhausted
X-Nexus-Required-Amount: 50000
X-Nexus-Currency: USD
X-Correlation-ID: 7f3a9c12-4e5b-4d8a-9f01-2b3c4d5e6f70
{"error":{"code":"Budget_Exhausted","required":"50000","currency":"USD"}}The correlation id#
X-Correlation-ID is on every response, success or failure. Log it. It is the one thing that lets us answer a question about a specific call — we do not store your payloads, so it is the handle on a request rather than a copy of it.