Request access

Errors and rate limits

Every error code the Node Lodge API returns, what each one means and what to do, and the request limits per minute and per hour.

Every error has the same shape. The HTTP status says what kind of failure it is; code says which one.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Retry in a moment.",
    "reference": "7F3K-92QD"
  }
}
  • code: stable, safe to branch on.
  • message: a sentence for a person. It can change.
  • reference: quote it to support to find the request.
  • fields: on VALIDATION_ERROR only, the fields that failed, each with a path and a message.

Error codes

Request

Code Status Meaning What to do
VALIDATION_ERROR 400 A field, the query or the JSON body is invalid. Fix the fields listed in fields.
AMBIGUOUS_CREDENTIALS 400 The request carries both a console session cookie and an API key. Send one of the two.
PAYLOAD_TOO_LARGE 413 The body is over 64 KiB. Send a smaller body.
IDEMPOTENCY_MISMATCH 422 The Idempotency-Key was already used with a different body. Use a new key for a new request.

Authentication and access

Code Status Meaning What to do
UNAUTHENTICATED 401 No valid session or API key. Check the Authorization: Bearer header, or create a new key.
FORBIDDEN 403 Your role, or the resource’s owner, does not allow this action. Ask an owner or admin of the organization.
API_KEY_NOT_ALLOWED 403 API keys cannot call this route, or the key lacks the scope. Add the scope to a new key, or use the console. See What a key can call.
EMAIL_NOT_VERIFIED 403 The account’s e-mail address is not confirmed. Open the confirmation link from your inbox.
TERMS_REQUIRED 403 The current terms of use are not accepted. Accept them in the console.
MFA_REQUIRED 403 The action needs two-factor authentication on. Turn it on in Settings.
STEP_UP_REQUIRED 403 The action needs a two-factor code from the last 10 minutes. Enter a fresh code, then retry.
MFA_CODE_INVALID 400 The two-factor code is wrong or expired. Enter the current code.
TOKEN_INVALID 400 An e-mail link is invalid or expired. Ask for a new link.
ACCOUNT_THROTTLED 429 Too many failed sign-ins or two-factor codes in 15 minutes. Wait 15 minutes.

Sessions, credit and limits

Code Status Meaning What to do
CREDIT_INSUFFICIENT 402 The budget is higher than the credit available. Add credit, or lower the budget.
FUNDS_INSUFFICIENT 402 The available funds do not cover the booking. Add credit, or book a shorter duration.
ACCOUNT_BLOCKED 402 A payment failed or was reversed, so new sessions are blocked. See Payment declined.
TRUST_LIMIT 403 The session goes past your account limits. Stop a session, pick another GPU class, or request a higher limit.
API_KEY_LIMIT 409 The session budget, its raise or the booking goes past a spending limit of the API key. Lower the budget, or raise the key’s limits with Edit limits. See Spending limits.
API_KEY_INVALID 409 The key that booked the session is no longer valid. Use a valid key.
MAX_COST_EXCEEDED 409 The booking costs more than the maximum you sent. Raise the maximum, or book less time.
BUDGET_EXCEEDED 409 The session is over the spending cap that applies to this offer. Lower the budget, or pick another offer.
RESOURCE_UNAVAILABLE 409 The machine went offline or was just rented. Pick another offer.
PARTNER_UNAVAILABLE 409 The offer changed or is gone. Reload the catalog and pick again.
SESSION_REQUIRED 409 Data-center machines start as sessions, with a budget. Launch it with POST /v1/sessions.
RESERVATION_REQUIRED 409 Data-center machines are booked as reservations on this account. Book it with POST /v1/reservations, then start it.
INVALID_STATE 409 The session is not in a state that allows this, for example already ended. Read the session, then act on its status.
CONFLICT 409 The resource already exists, or the same request is still running. Read the resource, or wait and retry.
NOT_FOUND 404 The resource does not exist or is not yours. Check the ID.

Limits and server

Code Status Meaning What to do
RATE_LIMITED 429 Too many requests. Wait for the seconds in retry-after, then retry.
INTERNAL_ERROR 500 The request failed on the server. Retry. If it persists, send the reference to support.

Rate limits

Limits count requests per window. With an API key, the general limit counts per key; without one, per IP address.

Requests Limit
Any API route, unless listed below 300 a minute
Sign-up and sign-in 10 a minute
Two-factor codes 10 a minute
Password reset request 5 in 15 minutes
API keys: create or edit limits 30 an hour
SSH keys: add 30 an hour
Card, credit and automatic top-up changes 20 an hour each
Support: new request 10 an hour
Support: reply, reopen, resolve 30 an hour each
Public GPU availability 60 a minute

Each answer carries the state of its limit:

  • x-ratelimit-limit: requests allowed in the window.
  • x-ratelimit-remaining: requests left.
  • x-ratelimit-reset: seconds until the window resets.

Past the limit, the answer is 429 RATE_LIMITED with a retry-after header in seconds. Wait that long, then retry. Back off further on repeated 429s.

Retry safely

  • Retry 429, 500 and network errors, never 4xx errors that name a field or a state.
  • Send an Idempotency-Key header (8 to 128 letters, digits, - or _) when you book or launch: a retry with the same key and body returns the first result instead of booking twice.

Last updated View as Markdown