Errors

Every Nodaro API error returns an HTTP status and one JSON envelope with a stable code, so your client can dispatch on the code instead of parsing messages. There are two kinds of failure: a request error, when the call itself is refused and nothing starts, and a job failure, when a generation that started fails later and reports why on the job.

The error envelope

{ "error": { "code": "rate_limited", "message": "Too many requests. Max 30 per minute." } }

• code is a stable slug. Dispatch on it.
• message is text for people. It can change, so never match on it.
• Some errors add fields, listed with each code below. Most sit inside error; already_running puts executionId beside error, and a failed pre-run allowance check puts required and remaining at the top level.

The OAuth token endpoint is the one exception: it answers in the OAuth format, for example { "error": "invalid_grant", "error_description": "…" }. See OAuth apps.

Which errors to retry

Three server errors need care:

• 503 price_not_configured does not succeed on retry: the model has no price on this deployment until its operator sets one.
• 503 provider_unavailable on the asynchronous structured LLM route is permanent on an install that sends its language-model calls to nodaro.ai.
• When publishing to social networks, 503 publish_retryable means nothing was posted and the same request is safe to send again, but 500 publish_failed means the outcome is unknown, and sending again can post twice.

Error codes

400 Bad Request

401 Unauthorized

402 Payment Required

These codes come from Nodaro Cloud and from deployments that bill.

403 Forbidden

404 Not Found

409 Conflict

413, 422 and 429

The 422 codes happen only on deployments that register such a policy. See Rate limits for the 429 codes.

500 and 503

When a job fails later

A request that succeeded can still produce a job that fails. The job then carries error_message, and for two kinds of failure a structured error_hint:

• { "kind": "safety-block", "class": "copyright" | "likeness" | "safety", "retried": boolean, "suggestedProvider"?: string } when a model's safety filter blocked the request.
• { "kind": "policy-block", "policyId": string, "reason": string, "hookPoint": "request" | "result" } when a deployment's policy rejected it.

Both are always refunded, and credit_status on the job shows it. Read Why a job failed for what each field means and when to try another model.

Errors in the SDK

@nodaro/sdk throws a typed error for every failed response. Catch the most specific class first:

import {
  NodaroError,
  ForbiddenError,
  InsufficientCreditsError,
  RateLimitedError,
} from '@nodaro/sdk'

try {
  await client.workflows.run(workflowId)
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    showPaywall({ required: err.required, available: err.available })
  } else if (err instanceof ForbiddenError && err.missingScope) {
    requestConsent([err.missingScope])
  } else if (err instanceof RateLimitedError) {
    await new Promise((r) => setTimeout(r, 5_000))
  } else if (err instanceof NodaroError) {
    console.error(`API error ${err.status} (${err.code}): ${err.message}`)
  } else {
    throw err // a network failure, not an API error
  }
}

The polling helpers add their own errors, such as JobFailedError and JobTimeoutError. See Run a single node.

Errors in the CLI

With --json, the CLI prints the payload and exits normally instead of using codes 2, 3 and 130, so check .status yourself.