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, 429 and 451

job_blocked and upload_blocked happen only on deployments that register such a policy. See Rate limits for the 429 codes.

500 and 503

Metered LLM requests

A language-model call is charged for the tokens it uses, so its credits are held before the call starts. A synchronous request of this kind, such as Generate Text, Prompt Helper or POST /v1/llm/structured, can answer two more codes:

• 409 job_cancelled. The job was cancelled after its credits were held, but before its call was sent. The call is never sent, and the hold is refunded. Do not retry the request as it is: the job was cancelled on purpose.
• 503 job_start_failed. The server could not record that the call is starting, so it did not send the call. The hold is refunded. Retry the request.

A model with no price yet

An LLM node is charged per model, at the rate of the lane that serves it. A model with no rate on that lane cannot be run. Every route that would price or run it answers 400:

{
  "error": {
    "code": "validation_error",
    "reason": "llm_model_unpriced",
    "modelId": "<model>",
    "message": "The model \"<model>\" has no price yet, so it cannot be run. Choose another model."
  }
}

• Estimates: POST /v1/credits/estimate-workflow, GET /v1/credits/model-cost, POST /v1/component/estimate-credits, POST /v1/workflows/:id/render-final/estimate and the /estimate route of each use-case node. POST /v1/credits/model-costs answers per key instead: it lists the key in errors, with an errorCodes entry.
• Publishing: POST /v1/apps/publish and POST /v1/templates/publish refuse before anything is written. A republish leaves the current version live.
• Runs: POST /v1/workflows/:id/run, POST /v1/app/:slug/run, POST /v1/app/:slug/runs/:runId/resume, POST /v1/component/execute, POST /v1/api/run, POST /v1/present/:token/run, and the run and continue routes of each use-case node. The check runs before the run is created, with your input overrides applied. No node runs, so nothing is charged. The MCP tools run_app, run_workflow and run_component reach the same routes.
• Triggers: a webhook fire answers the same 400. Schedule, Telegram and plugin-trigger fires are skipped. Each trigger leaves one failed execution with error_message: "llm_model_unpriced" in the workflow's history, and repeated fires add no more.
• Inside the run: the server checks again when a run starts, before any node runs. The check covers the sub-workflows and components the run executes. A run refused here ends failed, with the message above as its error_message. A model inside a sub-workflow adds Found inside Sub-workflow node <id>., and one inside a component adds Found inside Component node <id>.

Two read-only routes still describe the workflow. GET /v1/present/:token leaves out estimatedCost and returns estimatedCostUnpriced: { reason, modelId, message }. GET /v1/api/schema leaves out estimatedCredits and returns estimatedCreditsUnpriced in the same shape.

When a job fails later

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

• { "kind": "safety-block", "class": "copyright" | "likeness" | "safety", "retried": boolean, "suggestedProvider"?: string, "subject"?: "input_video" | "input_image" | "prompt" | "audio" } when a model's safety filter blocked the request. subject: "input_video" means the provider refused the job's input video itself, so send a different clip. subject: "input_image", always with class: "copyright", means the provider refused one of the job's input images as possibly copyrighted: send a different picture, because rephrasing the prompt will not help. subject: "prompt" means the provider's own words named the prompt, so change the prompt. subject: "audio" means the provider's own words blamed the generated audio, not the picture. Treat a subject you do not know as absent.
• { "kind": "policy-block", "policyId": string, "reason": string, "hookPoint": "request" | "result" } when a deployment's policy rejected it.
• { "kind": "credits", "code": string } when the job ran out of credits partway, for example insufficient_credits or a workspace limit such as budget_exceeded.
• { "kind": "input-refused", "subject": "input_video" } when the provider refused the job's input video without naming a content-policy class. No other model is suggested. Send a different clip.
• { "kind": "request-refused", "subject"?: "input_video" } when the provider refused the request as it was sent, naming a fault of it: a setting, a file's format or size, or the prompt's length. The same request is refused again, so change the input images, the video, the prompt or the settings. subject: "input_video" is there when the provider's words name the input video as the fault, such as its length or size, or no character found in it, so send a different clip. It is not a content-policy block.

A failed job also carries error_detail, the provider's own words, or null. The words go only to a caller who can open the run's workflow, and a deployment can keep them for its administrators. See The provider's own words.

The first three are refunded, and credit_status on the job shows it. A failed metered LLM call is the exception: usage the provider billed is charged. 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.