NodaroAccount
Docs do Nodaro
DocumentaçãoReferência de nósModelosTemplatesAgentes de IA (MCP)DesenvolvedoresAuto-hospedagemPesquisaComparações
API REST

Erros

Todo erro da API do Nodaro tem status HTTP e código estável em um envelope. Veja o que cada código significa, quais repetir e como tarefas relatam falhas.

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 tarefa acontece quando uma geração que começou falha depois e informa o motivo na tarefa.

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

StatusO que fazer
5xxNormalmente temporário. Tente de novo com backoff exponencial.
429Espere e tente de novo com backoff: por exemplo, 5, depois 10, depois 20 segundos. Respeite o cabeçalho Retry-After quando ele existir.
402Adicione créditos, ou peça orçamento a um administrador do espaço de trabalho, e tente de novo.
Outros 4xxCorrija a requisição primeiro. A mesma requisição falha 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

CódigoSignificado
validation_errorUm corpo malformado, um UUID inválido, um campo inválido ou um cursor malformado. Com reason: "llm_model_unpriced", um modelo de LLM que ainda não tem preço. Veja Um modelo ainda sem preço.
limit_reachedVocê já tem 10 tokens de API, ativos ou não. Exclua um primeiro.
invalid_workflowUma entrada de workflowIds de um token não é um workflow do seu espaço pessoal.
token_workspace_mismatchUm token vinculado a um espaço de trabalho foi enviado com um cabeçalho X-Nodaro-Workspace que indica outro.
locked_fieldUma execução tentou mudar para onde um nó externo envia dados ou de onde ele os busca. Veja O que uma execução não pode mudar.
image_requiredPOST /v1/generate-video sem quadro inicial, em um modelo que não consegue fazer vídeo a partir de texto. A mensagem diz se referências funcionariam no lugar dele.
sequence_execution_requiredA execução inclui nós de produção do Studio que precisam ser gerados pela API de produções do Studio.
not_workspace_scopedVocê mudou visibility em um workflow que não está em um espaço de trabalho.
advanced_mode_unsupportedadvancedMode: true em um modelo que não tem uma via direta.
media_link_bad_hostUm nó que mede um link de mídia antes da cobrança recebeu um link cujo host não existe, ou que aponta, ou redireciona, para um endereço privado ou reservado. A mensagem diz para verificar o link, ou para usar um link para um host público ou enviar o arquivo. Nada é reservado. Veja Links de mídia.
advanced_mode_unavailableadvancedMode: true enquanto o provedor do próprio modelo não aceita requisições. Nada é cobrado. Desative o Modo avançado para executar o modelo. O mesmo código pode chegar como 502 no meio da chamada. Nesse caso, ele é reembolsado, a menos que o provedor tenha cobrado a tentativa.
quote_unsupportedPOST /v1/quote para um tipo de nó que a plataforma não consegue cotar. A mensagem lista os tipos que ela consegue. Veja Cotações de execução.
continuation_subset_requiredcontinueFromExecutionId sem nodeIds nem continueMode. Veja Continuar uma execução.
continuation_workflow_mismatchA execução indicada em continueFromExecutionId executou outro workflow.
continuation_version_mismatchA execução indicada em continueFromExecutionId executou uma versão de app publicado do workflow.
render_final_node_not_foundrenderFinal.renderNodeId não indica nenhum nó do workflow.
media_unreadableUma execução de caso de uso, como Enxugar episódio, Índice de capítulos, Trailer do episódio, Pacote de clipes ou Layout de locutores, cuja gravação não pôde ser lida. Confira se o link abre e é um arquivo de vídeo ou de áudio. Nada é criado nem cobrado.
media_has_no_audioUma execução de caso de uso ou o orçamento dela: uma gravação não tem som para transcrever. A mensagem indica a gravação. Nada é criado nem cobrado.
media_too_longUma execução de caso de uso ou o orçamento dela: uma gravação, ou o áudio principal, tem mais de 3 horas. A mensagem indica qual. Nada é criado nem cobrado.
master_audio_unreadableUma execução de caso de uso ou o orçamento dela com masterAudioUrl: o áudio principal não pôde ser lido como áudio. Nada é criado nem cobrado.
render_final_not_a_renderrenderFinal.renderNodeId indica um nó que não é uma renderização do Aplicar EDL.
suno_cover_sourcePOST /v1/suno/cover com taskId e audioId que não podem ter cover por id, e sem uploadUrl. Exemplos são uma tarefa que não é uma música sua concluída, um audioId que não é uma das faixas da música, ou configurações que um cover por id não aceita. Envie o áudio como uploadUrl. Nada é cobrado. Veja Cover com Suno.
suno_wav_stemA conversão para WAV com Suno de um stem que não pode ser convertido: a separação não tem stems do Suno, ela não guardou os ids dos stems, ou audioId não é um dos stems dela. Execute a separação de novo se ela não guardou os ids. Nada é cobrado. Veja Converter para WAV com Suno.
suno_not_a_trackPOST /v1/suno/convert-wav, /v1/suno/extend ou /v1/suno/separate indicou uma tomada da Fala com Suno pelos ids do Suno. Uma tomada falada não é uma música. Nada é cobrado. Envie o áudio por URL onde a rota aceitar um.
media_link_not_a_fileUm link de mídia aponta para uma playlist ou um manifesto de transmissão contínua, como .m3u8 ou .mpd, ou para um formato que o servidor não lê, como um GIF. Envie o arquivo em vez disso. Nada é cobrado. Veja Links de mídia.

401 Unauthorized

CódigoSignificado
unauthorizedO token está ausente, é inválido, expirou ou foi revogado.

402 Payment Required

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

CódigoCampos extrasSignificado
insufficient_creditsrequired, balanceA conta ficou sem créditos. Em uma implantação com uma única conta de cobrança, significa que o saldo compartilhado da implantação está vazio: o erro então traz required, mas nunca balance, e só a conta de cobrança pode adicionar créditos. Uma execução de caso de uso de podcast ou a continuação dela (POST /v1/tighten-episode, /v1/episode-chapters, /v1/episode-trailer, /v1/clip-pack, /v1/speaker-layout e os /continue delas) compara o saldo com a estimativa de tudo o que executa antes de qualquer coisa começar. A recusa dela acrescenta estimate: true: required é então a estimativa da execução, não o preço, e a execução é cobrada pelo que usar.
insufficient_app_creditsA execução de um app publicado: a conta ficou sem créditos.
budget_exceededTrabalho pago por um espaço de trabalho: o orçamento do espaço de trabalho não cobre a execução. Peça mais a um administrador do espaço de trabalho.
member_cap_exceededTrabalho pago por um espaço de trabalho: o seu próprio limite de gastos nesse espaço de trabalho foi atingido.
user_allowance_exceededrequired, remainingUma implantação com uma única conta de cobrança que aplica limites de uso por usuário: o seu limite de uso não cobre a execução. Só a conta de cobrança pode aumentá-lo.
instance_cap_reachedUm token OAuth de uma instalação auto-hospedada conectada: a instalação gastou o limite mensal dela na conta que a conectou. Aumente ou remova o limite em Instâncias conectadas.

403 Forbidden

CódigoCampos extrasSignificado
forbiddenO token tem um escopo de workflows e a requisição está fora dele, ou a rota precisa de uma sessão com login. Veja Limitar um token a alguns workflows e Rotas que precisam de uma sessão com login.
access_blockedNo Nodaro Cloud e na Business edition, um administrador bloqueou a conta. Todas as credenciais da conta são recusadas: a sessão, os tokens de API e os tokens OAuth. Os agendamentos e gatilhos dela param, e os apps publicados dela respondem 404 not_found. Fale com o suporte se achar que é um engano.
insufficient_scopemissingScopeUm token OAuth não tem um escopo de que a rota precisa. Peça de novo o consentimento do usuário, com o escopo mais amplo.
mcp_client_not_allowedA implantação lista os clientes que podem usar o MCP, e este cliente ou token não é um deles. Veja Implantações que listam os clientes MCP.
developer_apps_admin_onlyNesta implantação, só administradores podem criar, alterar ou excluir apps de desenvolvedor, ou trocar os segredos deles. Ler os seus próprios apps continua funcionando.
in_app_onlyA rota existe só para o app web do Nodaro, como o Workflow Copilot.
node_not_availableEsta implantação não oferece à sua conta o nó, ou a opção que você escolheu nele. A mensagem diz qual é. Nada é cobrado. Toda rota que gasta créditos é verificada como o nó que ela executa, qualquer que seja o caminho: POST /v1/suno/generate como suno-generate, uma execução de tendência (POST /v1/trends/:slug/runs e seu /estimate) como cast-swap, o Video Remake, POST /v1/video-director/run como video-director, o Diretor de vídeo, e POST /v1/pipelines e as rotas de pipeline que iniciam ou continuam trabalho como film-pipeline, o pipeline de filme. Veja Pipelines.
suno_task_not_yoursPOST /v1/suno/cover indicou um taskId feito pela execução de outra conta, sem uploadUrl. Nada é cobrado. Com um uploadUrl, o arquivo recebe o cover como sempre.
model_not_availableA requisição seria executada em um modelo que esta implantação não oferece. É o modelo que você indicou ou, em uma implantação que restringe modelos, o padrão que a rota usa quando você não indica nenhum: o padrão de imagem para a proporção, o modelo de linguagem padrão de um recurso ou o único modelo fixo de uma rota. Nada é criado nem cobrado. Indique um modelo que GET /v1/models lista.
model_disabledSó no Nodaro Cloud. Um administrador desativou este modelo. Nada é reservado nem cobrado. Comprar créditos não resolve: escolha outro modelo, ou tente de novo quando o modelo for reativado.
edition_requiredrequired_editionA rota precisa de uma edição superior: cloud para a derivação de pipelines, business para o gerenciamento de tokens de API.
not_a_memberO cabeçalho X-Nodaro-Workspace indica um espaço de trabalho do qual você não é membro ativo.
member_suspendedA sua participação no espaço de trabalho está suspensa.
personal_space_disabledA sua organização só permite criar trabalho dentro de um espaço de trabalho. Envie o cabeçalho do espaço de trabalho.
project_create_not_allowedSó os administradores do espaço de trabalho podem criar projetos.
workspace_archivedUma escrita em um espaço de trabalho arquivado, como compartilhar um workflow. Criar trabalho nele responde 409 em vez disso.
not_permittedVocê não pode mover este workflow, ou não pode movê-lo para esse destino.
sso_requiredA implantação restringe o login ao provedor de identidade dela, e a conta desta sessão não foi criada por ele. Os tokens não são afetados.
subscription_requiredUma conta de pagamento por uso tentou gastar créditos pelo editor web. Os créditos do pagamento por uso funcionam pela API, pelo SDK, pela CLI e pelo MCP, então as chamadas com token nunca recebem este código.
api_tokens_payer_onlyEm uma implantação com uma única conta de cobrança, só essa conta pode criar tokens de API.
payer_balance_jwt_onlyEm uma implantação assim, a conta de cobrança leu o saldo compartilhado com um token. Só a própria sessão do navegador dela pode fazer isso.
payer_requiredUma rota de cobrança da implantação foi chamada por algo que não é a sessão do navegador da conta de cobrança.
rights_confirmation_required, rights_authorization_required e os outros códigos rights_confirmation_*Uma importação de link não tem uma confirmação de direitos de conteúdo que sirva. Nada foi buscado. Veja Direitos de conteúdo.
import_source_disabledA implantação não permite importações do site do link.
link_imports_disabledEsta implantação desligou as importações de links para outros sites. Envie o arquivo em vez disso. Um arquivo do próprio armazenamento da implantação não é recusado. Veja Direitos de conteúdo.
imports_blockedA importação de links está bloqueada na conta, ou a conta está encerrada, pela política de infratores reincidentes da implantação. A mensagem diz até quando. Veja Infratores reincidentes.

404 Not Found

CódigoSignificado
not_foundO recurso não existe, ou você não pode vê-lo. As duas situações têm deliberadamente a mesma resposta, para que um ID nunca revele se algo existe.
workspace_not_foundUm trabalho pago por um espaço de trabalho indica um espaço de trabalho que não existe.
continuation_not_foundA execução indicada em continueFromExecutionId não existe ou não é sua.
checkout_session_not_foundUma leitura de sessão do Checkout, ou um replacesSessionId, indica uma sessão que não é sua, não existe ou não é da mesma compra. Veja Substituir uma sessão anterior do Checkout.

409 Conflict

CódigoCampos extrasSignificado
already_runningexecutionIdO workflow já tem uma execução ativa, ou um Tentar novamente da execução do app está pendente. Em vez disso, consulte essa execução periodicamente.
continuation_not_completedA execução indicada em continueFromExecutionId ainda está em andamento, falhou ou foi cancelada. Só uma execução concluída pode ser continuada sem continueMode.
continuation_not_failedCom "continueMode": "from-failed": a execução não falhou.
continuation_supersededexecutionId, supersededByCom "continueMode": "from-failed": uma continuação mais recente da execução falhou, então continue essa, ou ela concluiu tudo o que faltava. Veja Continuar uma execução que falhou.
continuation_preview_pendingexecutionId, renderNodeIds, reviewNodeIds, nextCom "continueMode": "from-failed": a continuação mais recente parou em uma revisão de prévia. Envie next antes como corpo de uma execução.
continuation_subset_requiredCom "continueMode": "from-failed": não sobrou nada a continuar. Em um Tentar novamente de uma execução de app: todas as etapas foram concluídas.
app_run_version_changedappVersion, runVersionUm Tentar novamente de uma execução de app feita em outra versão do app. Comece a execução de novo.
app_run_version_unavailableUm Tentar novamente de uma execução de app cuja versão não está mais disponível. Comece a execução de novo.
workflow_conflictcurrentVersion, currentUpdatedAt, currentRecordO workflow mudou desde a versão que você enviou. Mescle as suas mudanças com currentRecord e salve de novo.
job_cancelledUma requisição síncrona de LLM medida cuja tarefa foi cancelada depois que os créditos foram reservados, mas antes de a chamada ser enviada. Veja Requisições de LLM medidas.
idempotency_key_reused—Uma execução do Enxugar episódio ou a continuação dela (POST /v1/tighten-episode, POST /v1/tighten-episode/continue): a Idempotency-Key já pertence a uma das suas tarefas de outro tipo, como uma geração de imagem. Nada é criado nem cobrado. Envie uma nova chave. Uma chave que pertence a uma execução do mesmo nó responde com essa execução, com 202 e "deduped": true.
batch_in_progressUma rota de lote (um lote de imagens com count ou models, /v1/generate-character, /v1/generate-creature, /v1/generate-location ou /v1/generate-object com count 2 ou mais, ou /v1/video-sfx com versions 2 ou mais) recebeu uma segunda requisição com a mesma Idempotency-Key enquanto outra requisição ainda está criando o lote. Nada mais foi criado nem cobrado. Tente de novo em instantes: ela retorna as mesmas tarefas.
workspace_archivedVocê tentou criar ou mover trabalho para um espaço de trabalho arquivado.
workspace_has_no_default_projectUma criação em um espaço de trabalho não indicou nenhum projeto, e o espaço de trabalho não tem nenhum. Indique um projeto.
move_blockedO trabalho foi criado para uma atividade e não pode ser movido.
production_capability_requiredUm salvamento genérico de workflow alterou uma produção do Studio que precisa da própria API.
retained_image_in_useUma exclusão removeria imagens protegidas, ou uma produção ainda tem tarefas usando essas imagens. Termine ou cancele essas tarefas primeiro.
content_heldO arquivo está retido como prova de uma reclamação, por isso não pode ser excluído agora. Veja Conteúdo restrito.
large_upload_unavailableA implantação verifica os bytes de todo envio, então o caminho de envio grande fica fechado. Envie um arquivo de até 500 MB com POST /v1/upload. Veja Enviar um arquivo grande de vídeo ou de áudio.
checkout_already_complete, checkout_in_progressUma requisição do Checkout com replacesSessionId: a sessão anterior já está paga, ou o pagamento dela ainda está sendo confirmado. Veja Substituir uma sessão anterior do Checkout.
not_applicableEm uma implantação em que uma conta de cobrança paga por todos os usuários, uma rota de créditos gratuitos de cadastro: POST /v1/credits/claim-signup-grant e as duas rotas da oferta de boas-vindas. Os créditos gratuitos de cadastro não valem ali, então nada é registrado nem concedido. Não há o que repetir, e um cliente que faz o pedido a cada carregamento de página pode ignorar a resposta.

413, 422, 429 e 451

StatusCódigoSignificado
413A sua conta passou do limite de armazenamento. O SDK lança StorageExceededError.
422job_blockedA política de tarefas ou a proteção de conteúdo da implantação recusou a geração antes da execução. Nenhuma tarefa foi criada e nada foi cobrado. Mostre message ao seu usuário como está e não repita a mesma requisição.
422upload_blockedA política de upload da implantação recusou um arquivo antes de ele ser armazenado. Mostre message como está.
422idempotency_key_reusedA Idempotency-Key de uma rota de lote já pertence a outra requisição: as tarefas de outra rota, ou as tarefas da mesma rota para outro corpo enquanto alguma delas ainda espera. Nada é criado nem cobrado. Envie a mesma requisição de novo, ou use uma chave nova.
422media_too_longO arquivo tem mais de 30 minutos, o máximo que uma mídia importada para o editor pode ter: um envio grande no complete, ou um link direto de vídeo em POST /v1/download-video. Nada é guardado nem contado no seu armazenamento.
422media_too_largeO arquivo passa de 10 GiB: um envio grande no start, ou um link direto de vídeo em POST /v1/download-video.
422media_bitrate_implausibleO arquivo é muito maior do que a duração dele permite: mais de 2.500 Mbit/s em média para vídeo, ou 50 Mbit/s para áudio, sem contar os primeiros 16 MiB.
422offsets_not_appliedO POST /v1/edit-plan recebeu um campo offsets bruto. Grave antes cada deslocamento na origem dele, como sources[].offsetMs. Veja Plano de edição.
422master_offsetO POST /v1/edit-plan recebeu um deslocamento diferente de 0 na origem mestre, ou na origem a partir da qual a transcrição foi feita. Nada é cobrado.
429rate_limitedO limite por token de um token de API pessoal.
429rate_limit_exceededQualquer outro limite: por endereço, por rota ou as execuções diárias de um app publicado.
429too_many_downloadsVocê já tem 4 importações de vídeo em andamento.
429too_many_open_uploadsVocê já tem 3 envios grandes abertos. Conclua ou aborte um deles. Um envio abandonado libera a vaga quando o token dele expira.
451content_restrictedGET /v1/download ou GET /v1/image-proxy recebeu o pedido de um arquivo que o Nodaro restringiu. Veja Conteúdo restrito.

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

StatusCódigoSignificado
500internal_errorUm erro do servidor ou uma falha de um serviço do qual ele depende. Tente de novo com backoff. Quando uma tarefa ou uma execução não pôde entrar na fila para começar, ela falha na hora, os créditos são reembolsados e a Idempotency-Key é liberada, então uma nova tentativa com a mesma chave começa uma nova. Um lote cujas tarefas começaram só em parte nomeia as que estão em execução em error.startedJobIds: acompanhe essas e envie a mesma requisição com a mesma chave de novo para começar só o restante.
502advanced_mode_unavailableUma chamada de LLM no Modo avançado foi recusada no meio pelo provedor do próprio modelo. A reserva é reembolsada, a menos que o provedor tenha cobrado a tentativa. Desative o Modo avançado para executar o modelo.
503provider_key_missingUma execução de caso de uso ou o orçamento dela que transcreve, em uma instalação self-hosted sem chave para esse provedor de transcrição e sem uma conexão com o Nodaro Cloud que o cubra. A mensagem indica a chave. Nada é criado.
503job_start_failedUma requisição síncrona de LLM medida não conseguiu registrar que a chamada dela está começando. Veja Requisições de LLM medidas.
503price_not_configuredO modelo solicitado não tem preço nesta implantação, então o servidor recusa em vez de cobrar errado. Tentar de novo não adianta.
503rate_limit_unavailableUma rota que gasta créditos não conseguiu verificar o limite de taxa dela. Tente de novo mais tarde.
503source_unreachable, probe_timeout, probe_unavailableUm link de mídia não pôde ser lido antes da cobrança: o host não pôde ser encontrado, a leitura esgotou o tempo, ou o servidor não conseguiu fazer a leitura naquele momento. Nada é cobrado. Execute a requisição de novo. Veja Links de mídia.
503provider_unavailableO provedor do modelo não está disponível.
503embedded_checkout_unavailableUma requisição do Checkout com uiMode: "embedded" em uma implantação que não tem formulário de pagamento dentro da página. Envie a pessoa para a página do Checkout.
503billing_unavailableO relatório de uso não está disponível nesta instância, ou a cobrança está indisponível por um momento para uma execução de espaço de trabalho de um Tentar novamente de um app. Tente de novo em breve.

Requisições de LLM medidas

Uma chamada a um modelo de linguagem é cobrada pelos tokens que usa, então os créditos dela são reservados antes de a chamada começar. Uma requisição síncrona desse tipo, como Gerar texto, o assistente de prompt ou POST /v1/llm/structured, pode responder mais dois códigos:

  • 409 job_cancelled. A tarefa foi cancelada depois que os créditos foram reservados, mas antes de a chamada ser enviada. A chamada nunca é enviada, e a reserva é reembolsada. Não tente a requisição de novo como está: a tarefa foi cancelada de propósito.
  • 503 job_start_failed. O servidor não conseguiu registrar que a chamada está começando, então não enviou a chamada. A reserva é reembolsada. Tente a requisição de novo.

Um modelo ainda sem preço

Um nó de LLM é cobrado por modelo, pela tarifa da via que o atende. Um modelo sem tarifa nessa via não pode ser executado. Toda rota que calcularia o preço dele ou o executaria responde 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."
  }
}
  • Estimativas: POST /v1/credits/estimate-workflow, GET /v1/credits/model-cost, POST /v1/component/estimate-credits, POST /v1/workflows/:id/render-final/estimate e a rota /estimate de cada nó de caso de uso. POST /v1/credits/model-costs responde por chave: ele lista a chave em errors, com uma entrada em errorCodes.
  • Publicação: POST /v1/apps/publish e POST /v1/templates/publish recusam antes de gravar qualquer coisa. Uma nova publicação deixa a versão atual no ar.
  • Execuções: 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 e as rotas de execução e de continuação de cada nó de caso de uso. A verificação roda antes de a execução ser criada, com as suas substituições de entrada aplicadas. Nenhum nó é executado, então nada é cobrado. As ferramentas MCP run_app, run_workflow e run_component chegam às mesmas rotas.
  • Gatilhos: um disparo de webhook responde o mesmo 400. Os disparos de agendamento, do Telegram e de gatilhos de plugin são pulados. Cada gatilho deixa uma execução com falha, com error_message: "llm_model_unpriced", no histórico do workflow, e disparos repetidos não acrescentam outras.
  • Dentro da execução: o servidor verifica de novo quando uma execução começa, antes de qualquer nó ser executado. A verificação cobre os subworkflows e os componentes que a execução executa. Uma execução recusada aqui termina como failed, com a mensagem acima como error_message. Um modelo dentro de um subworkflow acrescenta Found inside Sub-workflow node <id>., e um dentro de um componente acrescenta Found inside Component node <id>.

Duas rotas somente de leitura ainda descrevem o workflow. GET /v1/present/:token omite estimatedCost e retorna estimatedCostUnpriced: { reason, modelId, message }. GET /v1/api/schema omite estimatedCredits e retorna estimatedCreditsUnpriced no mesmo formato.

Quando uma tarefa falha depois

Uma requisição bem-sucedida ainda pode produzir uma tarefa que falha. A tarefa então traz error_message e, em cinco tipos de falha, um error_hint estruturado:

  • { "kind": "safety-block", "class": "copyright" | "likeness" | "safety", "retried": boolean, "suggestedProvider"?: string, "subject"?: "input_video" | "input_image" | "prompt" | "audio" } quando o filtro de segurança de um modelo bloqueou a requisição. subject: "input_video" significa que o provedor recusou o próprio vídeo de entrada da tarefa, então envie outro clipe. subject: "input_image", sempre com class: "copyright", significa que o provedor recusou uma das imagens de entrada da tarefa por possível violação de direitos autorais: envie outra imagem, porque reformular o prompt não vai ajudar. subject: "prompt" significa que as próprias palavras do provedor apontaram o prompt, então mude o prompt. subject: "audio" significa que as próprias palavras do provedor culparam o áudio gerado, e não a imagem. Trate um subject que você não conhece como ausente.
  • { "kind": "policy-block", "policyId": string, "reason": string, "hookPoint": "request" | "result" } quando a política de uma implantação rejeitou a requisição.
  • { "kind": "credits", "code": string } quando a tarefa ficou sem créditos no meio da execução, por exemplo com insufficient_credits ou um limite do espaço de trabalho como budget_exceeded.
  • { "kind": "input-refused", "subject": "input_video" } quando o provedor recusou o vídeo de entrada da tarefa sem indicar uma classe de política de conteúdo. Nenhum outro modelo é sugerido. Envie outro clipe.
  • { "kind": "request-refused", "subject"?: "input_video" } quando o provedor recusou a requisição como ela foi enviada, indicando um defeito dela: uma configuração, o formato ou o tamanho de um arquivo, ou o comprimento do prompt. A mesma requisição é recusada de novo, então mude as imagens de entrada, o vídeo, o prompt ou as configurações. subject: "input_video" aparece quando as palavras do provedor apontam o vídeo de entrada como o defeito, como a duração ou o tamanho dele, ou nenhum personagem encontrado nele, então envie outro clipe. Não é um bloqueio por política de conteúdo.

Uma tarefa que falhou também traz error_detail, as palavras do próprio provedor, ou null. As palavras vão só para quem pode abrir o workflow da execução, e uma implantação pode reservá-las aos administradores dela. Veja As palavras do próprio provedor.

Os três primeiros casos são reembolsados, e o credit_status da tarefa mostra isso. Uma chamada de LLM medida que falhou é a exceção: o uso que o provedor cobrou é cobrado. Leia Por que uma tarefa 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:

ClasseStatusCampos extras
UnauthorizedError401
ForbiddenError403missingScope quando o código é insufficient_scope
ModelUnavailableError403Uma subclasse de ForbiddenError para model_not_available e model_disabled: quem é recusado é o modelo, não quem chama
NotFoundError404
InsufficientCreditsError402required, available. code é o próprio código 402 da recusa.
CreditCapExceededError402Uma subclasse de InsufficientCreditsError para budget_exceeded, member_cap_exceeded e user_allowance_exceeded: um limite que outra pessoa definiu
StorageExceededError413reason: storage_limit_exceeded para um armazenamento cheio, file_too_large para um arquivo acima do limite
WorkflowConflictError409currentVersion, currentUpdatedAt, currentRecord. Também usado no conflito production_busy do Studio.
AlreadyRunningError409executionId: a execução em andamento, para already_running
AppRunVersionChangedError409runVersion, appVersion, para app_run_version_changed
RateLimitedError429
JobBlockedError422
StudioOpError4xxopIndex: qual operação de um lote do Studio foi recusada
NodaroErrorqualquerA classe base: code, status, message e details, os outros campos do envelope
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

Código de saídaSignificado
0Sucesso.
1Não autorizado, não encontrado, um argumento errado ou um erro de rede.
2O --watch terminou e a execução falhou.
3O --watch parou porque a tarefa está retida para revisão. Não é uma falha: verifique de novo mais tarde.
130O --watch terminou e a execução foi cancelada.

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.

Perguntas frequentes

Como é um erro da API do Nodaro?

Todo erro tem um status HTTP e o corpo { "error": { "code": "…", "message": "…" } }. O código é estável, então baseie o tratamento nele. A mensagem é para pessoas e pode mudar.

Quais erros da API do Nodaro devo tentar de novo?

Tente de novo os erros 5xx e o 429 com backoff exponencial, por exemplo depois de 5, 10 e 20 segundos. Não repita uma requisição que deu erro 4xx sem mudá-la, porque a mesma requisição falha de novo. Entre os erros de servidor, 503 price_not_configured é a exceção.

O que significa 402 insufficient_credits?

A conta não tem créditos suficientes para iniciar a execução. O erro traz required, os créditos de que a execução precisa, e normalmente balance. Adicione créditos no Nodaro Cloud e envie a requisição de novo.

O que é error_hint em uma tarefa com falha?

É um motivo estruturado anexado a uma tarefa com falha em cinco tipos de falha: o filtro de segurança de um modelo, a política de uma implantação, a falta de créditos no meio da execução, um vídeo de entrada recusado e uma requisição que o provedor recusou como foi enviada. Leia esse campo em vez de analisar error_message, por exemplo para oferecer o modelo sugerido.

O que significa llm_model_unpriced?

O workflow ou a requisição indica um modelo de LLM que ainda não tem preço na via em que seria executado, então ele não pode ser executado. A resposta é 400 validation_error com reason llm_model_unpriced e o modelId. Escolha outro modelo. Nada é cobrado.

Por que uma rota responde 403 in_app_only?

A rota existe só para a sessão do próprio app web do Nodaro, por exemplo o Workflow Copilot ou as credenciais salvas da Saída de webhook. Tokens de API e tokens OAuth não podem chamá-la. Em vez disso, use os endpoints de workflow, o SDK ou o MCP.

Última atualização

Nesta página