Erros

Todo erro da API do Nodaro retorna um status HTTP e um envelope JSON com um code estável, para que o seu cliente decida o tratamento pelo código em vez de analisar mensagens. Há dois tipos de falha. Um erro de requisição acontece quando a própria chamada é recusada e nada começa. Uma falha de job acontece quando uma geração que começou falha depois e informa o motivo no job.

O envelope de erro

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

• code é um slug estável. Decida o tratamento por ele.
• message é um texto para pessoas. Ele pode mudar, então nunca use esse texto em comparações.
• Alguns erros adicionam campos, listados com cada código abaixo. A maioria fica dentro de error. already_running coloca executionId ao lado de error, e uma verificação de limite de uso que falha antes da execução coloca required e remaining no nível superior.

O endpoint de token do OAuth é a única exceção: ele responde no formato do OAuth, por exemplo { "error": "invalid_grant", "error_description": "…" }. Veja Apps OAuth.

Quais erros tentar de novo

Três erros de servidor exigem cuidado:

• 503 price_not_configured não dá certo em uma nova tentativa: o modelo não tem preço nesta implantação até o operador dela definir um.
• 503 provider_unavailable na rota assíncrona de saída estruturada de LLM é permanente em uma instalação que envia as chamadas de modelos de linguagem para o nodaro.ai.
• Na publicação em redes sociais, 503 publish_retryable significa que nada foi publicado e que é seguro enviar a mesma requisição de novo. Já 500 publish_failed significa que o resultado é desconhecido, e enviar de novo pode publicar duas vezes.

Códigos de erro

400 Bad Request

401 Unauthorized

402 Payment Required

Estes códigos vêm do Nodaro Cloud e das implantações que fazem cobrança.

403 Forbidden

404 Not Found

409 Conflict

413, 422 e 429

Os códigos job_blocked e upload_blocked só acontecem em implantações que registram uma política desse tipo. Veja Limites de taxa para os códigos 429.

500 e 503

Quando um job falha depois

Uma requisição bem-sucedida ainda pode produzir um job que falha. O job então traz error_message e, em dois tipos de falha, um error_hint estruturado:

• { "kind": "safety-block", "class": "copyright" | "likeness" | "safety", "retried": boolean, "suggestedProvider"?: string } quando o filtro de segurança de um modelo bloqueou a requisição.
• { "kind": "policy-block", "policyId": string, "reason": string, "hookPoint": "request" | "result" } quando a política de uma implantação rejeitou a requisição.

Os dois casos são sempre reembolsados, e o credit_status do job mostra isso. Leia Por que um job falhou para saber o que cada campo significa e quando tentar outro modelo.

Erros no SDK

O @nodaro/sdk lança um erro tipado para cada resposta com falha. Capture primeiro a classe mais específica:

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
  }
}

As funções auxiliares de consulta periódica adicionam erros próprios, como JobFailedError e JobTimeoutError. Veja Executar um único nó.

Erros na CLI

Com --json, a CLI imprime o payload e sai normalmente em vez de usar os códigos 2, 3 e 130, então verifique .status você mesmo.