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_runningcolocaexecutionIdao lado deerror, e uma verificação de limite de uso que falha antes da execução colocarequirederemainingno 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
| Status | O que fazer |
|---|---|
5xx | Normalmente temporário. Tente de novo com backoff exponencial. |
429 | Espere e tente de novo com backoff: por exemplo, 5, depois 10, depois 20 segundos. Respeite o cabeçalho Retry-After quando ele existir. |
402 | Adicione créditos, ou peça orçamento a um administrador do espaço de trabalho, e tente de novo. |
Outros 4xx | Corrija a requisição primeiro. A mesma requisição falha de novo. |
Três erros de servidor exigem cuidado:
503 price_not_configurednã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_unavailablena 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_retryablesignifica que nada foi publicado e que é seguro enviar a mesma requisição de novo. Já500 publish_failedsignifica que o resultado é desconhecido, e enviar de novo pode publicar duas vezes.
Códigos de erro
400 Bad Request
| Código | Significado |
|---|---|
validation_error | Um 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_reached | Você já tem 10 tokens de API, ativos ou não. Exclua um primeiro. |
invalid_workflow | Uma entrada de workflowIds de um token não é um workflow do seu espaço pessoal. |
token_workspace_mismatch | Um token vinculado a um espaço de trabalho foi enviado com um cabeçalho X-Nodaro-Workspace que indica outro. |
locked_field | Uma 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_required | POST /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_required | A execução inclui nós de produção do Studio que precisam ser gerados pela API de produções do Studio. |
not_workspace_scoped | Você mudou visibility em um workflow que não está em um espaço de trabalho. |
advanced_mode_unsupported | advancedMode: true em um modelo que não tem uma via direta. |
media_link_bad_host | Um 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_unavailable | advancedMode: 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_unsupported | POST /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_required | continueFromExecutionId sem nodeIds nem continueMode. Veja Continuar uma execução. |
continuation_workflow_mismatch | A execução indicada em continueFromExecutionId executou outro workflow. |
continuation_version_mismatch | A execução indicada em continueFromExecutionId executou uma versão de app publicado do workflow. |
render_final_node_not_found | renderFinal.renderNodeId não indica nenhum nó do workflow. |
media_unreadable | Uma 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_audio | Uma 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_long | Uma 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_unreadable | Uma 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_render | renderFinal.renderNodeId indica um nó que não é uma renderização do Aplicar EDL. |
suno_cover_source | POST /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_stem | A 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_track | POST /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_file | Um 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ódigo | Significado |
|---|---|
unauthorized | O 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ódigo | Campos extras | Significado |
|---|---|---|
insufficient_credits | required, balance | A 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_credits | A execução de um app publicado: a conta ficou sem créditos. | |
budget_exceeded | Trabalho 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_exceeded | Trabalho pago por um espaço de trabalho: o seu próprio limite de gastos nesse espaço de trabalho foi atingido. | |
user_allowance_exceeded | required, remaining | Uma 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_reached | Um 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ódigo | Campos extras | Significado |
|---|---|---|
forbidden | O 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_blocked | No 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_scope | missingScope | Um 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_allowed | A 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_only | Nesta 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_only | A rota existe só para o app web do Nodaro, como o Workflow Copilot. | |
node_not_available | Esta 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_yours | POST /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_available | A 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_disabled | Só 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_required | required_edition | A rota precisa de uma edição superior: cloud para a derivação de pipelines, business para o gerenciamento de tokens de API. |
not_a_member | O cabeçalho X-Nodaro-Workspace indica um espaço de trabalho do qual você não é membro ativo. | |
member_suspended | A sua participação no espaço de trabalho está suspensa. | |
personal_space_disabled | A 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_allowed | Só os administradores do espaço de trabalho podem criar projetos. | |
workspace_archived | Uma escrita em um espaço de trabalho arquivado, como compartilhar um workflow. Criar trabalho nele responde 409 em vez disso. | |
not_permitted | Você não pode mover este workflow, ou não pode movê-lo para esse destino. | |
sso_required | A 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_required | Uma 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_only | Em uma implantação com uma única conta de cobrança, só essa conta pode criar tokens de API. | |
payer_balance_jwt_only | Em 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_required | Uma 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_disabled | A implantação não permite importações do site do link. | |
link_imports_disabled | Esta 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_blocked | A 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ódigo | Significado |
|---|---|
not_found | O 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_found | Um trabalho pago por um espaço de trabalho indica um espaço de trabalho que não existe. |
continuation_not_found | A execução indicada em continueFromExecutionId não existe ou não é sua. |
checkout_session_not_found | Uma 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ódigo | Campos extras | Significado |
|---|---|---|
already_running | executionId | O 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_completed | A 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_failed | Com "continueMode": "from-failed": a execução não falhou. | |
continuation_superseded | executionId, supersededBy | Com "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_pending | executionId, renderNodeIds, reviewNodeIds, next | Com "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_required | Com "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_changed | appVersion, runVersion | Um Tentar novamente de uma execução de app feita em outra versão do app. Comece a execução de novo. |
app_run_version_unavailable | Um Tentar novamente de uma execução de app cuja versão não está mais disponível. Comece a execução de novo. | |
workflow_conflict | currentVersion, currentUpdatedAt, currentRecord | O workflow mudou desde a versão que você enviou. Mescle as suas mudanças com currentRecord e salve de novo. |
job_cancelled | Uma 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_progress | Uma 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_archived | Você tentou criar ou mover trabalho para um espaço de trabalho arquivado. | |
workspace_has_no_default_project | Uma 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_blocked | O trabalho foi criado para uma atividade e não pode ser movido. | |
production_capability_required | Um salvamento genérico de workflow alterou uma produção do Studio que precisa da própria API. | |
retained_image_in_use | Uma exclusão removeria imagens protegidas, ou uma produção ainda tem tarefas usando essas imagens. Termine ou cancele essas tarefas primeiro. | |
content_held | O arquivo está retido como prova de uma reclamação, por isso não pode ser excluído agora. Veja Conteúdo restrito. | |
large_upload_unavailable | A 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_progress | Uma 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_applicable | Em 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
| Status | Código | Significado |
|---|---|---|
| 413 | A sua conta passou do limite de armazenamento. O SDK lança StorageExceededError. | |
| 422 | job_blocked | A 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. |
| 422 | upload_blocked | A política de upload da implantação recusou um arquivo antes de ele ser armazenado. Mostre message como está. |
| 422 | idempotency_key_reused | A 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. |
| 422 | media_too_long | O 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. |
| 422 | media_too_large | O arquivo passa de 10 GiB: um envio grande no start, ou um link direto de vídeo em POST /v1/download-video. |
| 422 | media_bitrate_implausible | O 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. |
| 422 | offsets_not_applied | O POST /v1/edit-plan recebeu um campo offsets bruto. Grave antes cada deslocamento na origem dele, como sources[].offsetMs. Veja Plano de edição. |
| 422 | master_offset | O 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. |
| 429 | rate_limited | O limite por token de um token de API pessoal. |
| 429 | rate_limit_exceeded | Qualquer outro limite: por endereço, por rota ou as execuções diárias de um app publicado. |
| 429 | too_many_downloads | Você já tem 4 importações de vídeo em andamento. |
| 429 | too_many_open_uploads | Você já tem 3 envios grandes abertos. Conclua ou aborte um deles. Um envio abandonado libera a vaga quando o token dele expira. |
| 451 | content_restricted | GET /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
| Status | Código | Significado |
|---|---|---|
| 500 | internal_error | Um 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. |
| 502 | advanced_mode_unavailable | Uma 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. |
| 503 | provider_key_missing | Uma 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. |
| 503 | job_start_failed | Uma requisição síncrona de LLM medida não conseguiu registrar que a chamada dela está começando. Veja Requisições de LLM medidas. |
| 503 | price_not_configured | O 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. |
| 503 | rate_limit_unavailable | Uma rota que gasta créditos não conseguiu verificar o limite de taxa dela. Tente de novo mais tarde. |
| 503 | source_unreachable, probe_timeout, probe_unavailable | Um 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. |
| 503 | provider_unavailable | O provedor do modelo não está disponível. |
| 503 | embedded_checkout_unavailable | Uma 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. |
| 503 | billing_unavailable | O 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/estimatee a rota/estimatede cada nó de caso de uso.POST /v1/credits/model-costsresponde por chave: ele lista a chave emerrors, com uma entrada emerrorCodes. - Publicação:
POST /v1/apps/publishePOST /v1/templates/publishrecusam 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/rune 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 MCPrun_app,run_workflowerun_componentchegam à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, comerror_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 comoerror_message. Um modelo dentro de um subworkflow acrescentaFound inside Sub-workflow node <id>., e um dentro de um componente acrescentaFound 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 comclass: "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 umsubjectque 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 cominsufficient_creditsou um limite do espaço de trabalho comobudget_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:
| Classe | Status | Campos extras |
|---|---|---|
UnauthorizedError | 401 | |
ForbiddenError | 403 | missingScope quando o código é insufficient_scope |
ModelUnavailableError | 403 | Uma subclasse de ForbiddenError para model_not_available e model_disabled: quem é recusado é o modelo, não quem chama |
NotFoundError | 404 | |
InsufficientCreditsError | 402 | required, available. code é o próprio código 402 da recusa. |
CreditCapExceededError | 402 | Uma subclasse de InsufficientCreditsError para budget_exceeded, member_cap_exceeded e user_allowance_exceeded: um limite que outra pessoa definiu |
StorageExceededError | 413 | reason: storage_limit_exceeded para um armazenamento cheio, file_too_large para um arquivo acima do limite |
WorkflowConflictError | 409 | currentVersion, currentUpdatedAt, currentRecord. Também usado no conflito production_busy do Studio. |
AlreadyRunningError | 409 | executionId: a execução em andamento, para already_running |
AppRunVersionChangedError | 409 | runVersion, appVersion, para app_run_version_changed |
RateLimitedError | 429 | |
JobBlockedError | 422 | |
StudioOpError | 4xx | opIndex: qual operação de um lote do Studio foi recusada |
NodaroError | qualquer | A 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ída | Significado |
|---|---|
0 | Sucesso. |
1 | Não autorizado, não encontrado, um argumento errado ou um erro de rede. |
2 | O --watch terminou e a execução falhou. |
3 | O --watch parou porque a tarefa está retida para revisão. Não é uma falha: verifique de novo mais tarde. |
130 | O --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.
Páginas relacionadas
Tarefas
Limites de taxa
Autenticação
Créditos
SDK para TypeScript
Última atualização
Créditos
Leia saldo e histórico de créditos, liste planos e preços, calcule o preço de modelos e execuções antes de iniciá-las e entenda reservas e reembolsos.
Limites de taxa
Por padrão, um token de API do Nodaro aceita 30 execuções por minuto, até 120. Veja limites por rota, os dois códigos 429, tamanhos de lote e backoff.