Erros do Plan

Todo erro do Plan responde com um status HTTP e um corpo JSON. Decida pelo code, feito para máquinas, nunca pelo detail, feito para pessoas:

{
  "detail": "This task changed since you loaded it.",
  "code": "version_conflict",
  "extra": { "current_version": 9 }
}

Já os erros de validação no corpo de uma requisição respondem 400 com um mapa de mensagens por campo e sem a chave code. Por exemplo, um quadro criado sem o seu projeto:

{ "project": ["This field is required."] }

Procure code primeiro; se não existir, leia o mapa de campos. As regras compartilhadas por todas as APIs do Dailybot, incluindo as novas tentativas, estão em Erros.

Durante a Beta, o 402 é esperado

Até que sua organização seja habilitada na Beta do Plan, todos os endpoints do Plan respondem 402 plan_upgrade_required, seja qual for a credencial que você usar. Isso é esperado, não é um bug: escreva para [email protected] para participar. GET /v1/plan/entitlements/ é o único endpoint do Plan que nunca responde 402, então você pode consultar o estado antes.

402 e 503 significam coisas diferentes

Resposta	Significado	Leituras	Escritas
402 plan_upgrade_required	O Plan não está habilitado para sua organização (uma questão de plano ou da Beta)	Recusadas	Recusadas
503 feature_temporarily_read_only	O Plan está temporariamente somente leitura durante um incidente	Continuam funcionando	Recusadas, tente de novo mais tarde

Trate os dois separadamente. Um 503 nunca significa que você perdeu o acesso: as leituras continuam funcionando para que você sempre possa exportar seu trabalho.

O 404 nunca revela o que existe

Uma tarefa, quadro ou projeto que não existe e um que pertence a outra organização retornam o mesmo corpo 404. Os filtros se comportam da mesma forma: uma chave de quadro que não corresponde a nada seu simplesmente não encontra nada.

Todos os códigos

400 Bad Request: a requisição não pôde ser aceita como foi enviada

Código	Status	Significado	O que fazer
actor_required	400	A chamada precisa de uma pessoa, mas a credencial é uma key de agente ou da organização (por exemplo, owner=me).	Use uma sessão iniciada ou uma API key pessoal, ou envie o uuid de um usuário em vez de me.
attachment_invalid_type	400	Esse tipo de arquivo não é compatível. São aceitos imagens PNG, JPEG, GIF e WebP; PDF; texto simples e Markdown; ZIP; e arquivos do Word, Excel e PowerPoint. O servidor verifica o conteúdo real do arquivo, não só o tipo declarado.	Envie um arquivo de um tipo compatível.
attachment_limit_reached	400	A tarefa, o comentário, a meta ou o projeto já tem 50 anexos, o máximo.	Remova um anexo antes de adicionar outro.
attachment_too_large	400	O arquivo é maior que o permitido: 25 MiB com uploads pré-assinados de tarefas, 5 MiB em uma única requisição multipart (a única forma de anexar a um comentário, meta ou projeto) ou em servidores sem armazenamento de objetos. extra.max_size_bytes indica o limite.	Em uma tarefa, use presign → upload → confirmação; caso contrário, envie um arquivo menor.
channel_not_found	400	Um id de canal que a plataforma conectada não conhece, ou um canal privado onde é exigido um público (extra.parameter: "channel").	Escolha um external_id de GET /v1/plan/channels/ (type=channel para um destino pessoal).
comment_body_too_long	400	O comentário passa de 10.000 caracteres.	Encurte o texto ou divida em vários comentários.
delta_window_expired	400	O cursor delta tem mais de 7 dias.	Leia o snapshot do quadro de novo e continue a partir do delta_cursor dele.
description_too_long	400	A descrição da tarefa passa de 50.000 caracteres.	Encurte a descrição ou passe os detalhes para um anexo.
favorite_limit_reached	400	Você já tem 50 favoritos.	Desafixe um antes de fixar outro.
idempotency_key_required	400	Uma chamada em lote foi enviada sem Idempotency-Key.	Adicione o header; operações em lote sempre exigem esse header.
invalid_agent_attribution	400	O nome do agente passa de 128 caracteres, usa caracteres fora de letras, números, espaços e . - _ ( ) ' # + / & , :, pertence a um agente desativado, ou o valor de X-Dailybot-Agent-Name não pode ser decodificado como UTF-8 codificado em percent-encoding; ou uma key do tipo agente enviou um nome de agente. Nomes nunca são truncados.	Encurte o nome e codifique o header com percent-encoding, ou remova o nome ao chamar com uma key de agente. Veja Convenções do Plan.
invalid_date_range	400	Uma data ou um intervalo de datas está mal formatado (as datas são YYYY-MM-DD).	Corrija o formato da data.
invalid_filter_value	400	Não foi possível interpretar um filtro, um token de include ou um valor da consulta (por exemplo, state=overdue). extra.parameter indica qual.	Corrija o valor; veja Convenções do Plan.
invalid_idempotency_key	400	A Idempotency-Key não é uma chave válida (de 8 a 128 caracteres).	Envie uma chave de 8 a 128 caracteres, por exemplo um UUID.
invalid_label_filter	400	Um valor do filtro label não é um uuid de etiqueta, ou há mais de 50.	Envie até 50 uuids de etiqueta.
invalid_relation	400	O vínculo ou a referência não é válido. Por exemplo: uma tarefa relacionada a ela mesma ou a uma tarefa de outro espaço de trabalho, uma tarefa definida como sua própria tarefa pai, o limite de blocks da tarefa atingido, uma resposta a outra resposta (as conversas têm um só nível), uma resposta a um comentário de outra tarefa ou uma operação em lote desconhecida. detail indica qual.	Leia detail e corrija a referência.
invalid_schedule	400	Um campo do agendamento de um relatório ou do resumo é inválido: extra.parameter é weekdays, time, timezone, channel ou kind.	Envie dias ISO 1–7 (exatamente um para um relatório semanal), HH:MM, um fuso horário IANA, e um canal ou destinatários de e-mail.
invalid_sort	400	Esta lista não aceita o valor de sort.	Use uma chave de ordenação documentada pelo endpoint.
last_done_state	400	Um quadro precisa manter pelo menos uma coluna ativa na categoria done; arquivar ou mudar a categoria da última é recusado.	Adicione outra coluna done primeiro.
milestone_not_on_project	400	O marco pertence a um projeto diferente do projeto do quadro da tarefa.	Escolha um marco do projeto do quadro.
move_board_state_invalid	400	Uma movimentação para outro quadro indicou um estado de destino (ou um mapa de estados) que não corresponde ao quadro de destino.	Envie um state do quadro de destino, ou um state_map válido.
notification_routes_limit_reached	400	A organização já tem 10 rotas de canal (extra.limit).	Apague ou reutilize uma rota.
participant_cannot_access_board	400	A pessoa definida como responsável ou participante não consegue ver o quadro.	Dê acesso ao quadro primeiro, ou escolha alguém de …/mentionables/.
platform_not_connected	400	A organização não tem uma plataforma de chat para publicar ou buscar canais.	Conecte primeiro o Slack, o Microsoft Teams, o Discord ou o Google Chat.
reaction_invalid_emoji	400	A reação precisa ser um único emoji (no máximo 32 caracteres).	Envie um único emoji.
reaction_limit_reached	400	Você já tem o máximo de emojis diferentes neste comentário ou atualização (extra.limit).	Remova primeiro uma das suas reações.
report_schedules_limit_reached	400	A organização já tem 10 relatórios agendados (extra.limit).	Apague ou reutilize um relatório agendado.
route_scope_not_org_visible	400	O escopo de uma rota ou relatório nomeia um quadro ou projeto só para membros (extra.uuids). Canais só recebem o que todo o espaço de trabalho pode ver.	Remova esses uuids do escopo.
search_query_too_long	400	O texto da busca passa de 256 caracteres.	Encurte a busca.
search_query_too_short	400	O texto da busca tem menos de 2 caracteres.	Envie pelo menos 2 caracteres.
state_not_on_board	400	O estado indicado não pertence ao quadro da tarefa.	Use um uuid de estado de GET …/boards/{board_id}/states/.
states_reorder_invalid	400	A lista de reordenação não inclui cada coluna ativa exatamente uma vez.	Envie o uuid de cada estado ativo uma vez, na ordem.
subtask_cross_board	400	Uma subtarefa precisa estar no mesmo quadro da tarefa pai. Também é retornado ao mover para outro quadro uma tarefa que ainda tem subtarefas ativas, ou que é ela mesma subtarefa de uma tarefa do quadro de origem.	Desvincule ou mova as subtarefas primeiro, ou mantenha a tarefa no quadro da tarefa pai.
subtask_depth_exceeded	400	As subtarefas só se aninham em um nível.	Vincule a subtarefa a uma tarefa de primeiro nível.
too_many_filter_values	400	Um filtro repetível tem mais de 50 valores (extra.limit informa o número exato).	Envie menos valores por requisição.
too_many_items	400	A chamada em lote tem mais de 100 itens.	Divida em chamadas de até 100 itens.
unknown_field	400	Um campo do corpo que o endpoint não aceita (extra.parameter o nomeia). É recusado, nunca descartado em silêncio.	Remova o campo.
unknown_notification_kind	400	Um tipo de notificação que não está no catálogo (extra.parameter: "kind").	Use uma key de GET /v1/plan/notifications/catalog/: tipos pessoais para as suas chaves, tipos da organização para uma rota.
update_body_too_long	400	A atualização do projeto passa de 20.000 caracteres (extra.max_length).	Encurte a atualização.
version_precondition_ambiguous	400	If-Match e o campo version do corpo foram enviados juntos, com valores diferentes.	Envie só um dos dois.
view_limit_reached	400	Você já tem 20 visualizações salvas pessoais neste quadro, o limite.	Exclua uma visualização antes de salvar outra.

401 Unauthorized: a credencial está ausente ou não é válida

Código	Status	Significado	O que fazer
api_key_owner_inactive	401	A pessoa dona da API key foi desativada.	Crie uma chave para uma pessoa ativa.
credential_absent	401	Nenhuma credencial foi enviada.	Envie Authorization: Bearer … ou X-API-KEY.
credential_expired	401	A credencial expirou.	Entre de novo (dailybot login) ou use uma chave válida.
credential_malformed	401	Não foi possível ler a credencial.	Confira o nome e o valor do header.
invalid_credentials	401	A chave ou o token não existe.	Use uma credencial válida.
plan_free_api_keys_forbidden	401	As API keys não estão disponíveis no plano gratuito.	Use um token de usuário da CLI, ou faça upgrade do plano.
plan_missing_core_api_integrations	401	O plano da organização não inclui acesso à API.	Mude para um plano com acesso à API.

402 Payment Required: o Plan não está habilitado, ou um limite do plano foi atingido

Código	Status	Significado	O que fazer
plan_upgrade_required	402	O Plan ainda não está habilitado para sua organização. Isso é esperado durante a Beta. (Um login da CLI no plano gratuito recebe 403 com o mesmo código.)	Escreva para [email protected] para participar da Beta. GET /v1/plan/entitlements/ mostra o estado.
task_boards_limit_reached	402	O limite do plano para quadros foi atingido (o plano gratuito inclui até 3 quadros).	Arquive um quadro para liberar uma vaga, ou faça upgrade.
task_projects_limit_reached	402	O limite do plano para projetos foi atingido (o plano gratuito inclui 1 projeto).	Arquive um projeto para liberar uma vaga, ou faça upgrade.

403 Forbidden: você entrou, mas não tem permissão

Código	Status	Significado	O que fazer
attachment_delete_forbidden	403	Só quem enviou o anexo ou quem administra a organização pode removê-lo; em um comentário, quem escreveu o comentário também pode.	Peça a quem enviou o anexo, a quem escreveu o comentário ou a quem administra a organização.
comment_not_author	403	Só quem escreveu este comentário pode editá-lo, excluí-lo ou anexar arquivos a ele.	Peça a quem escreveu o comentário.
guest_not_allowed	403	Contas de convidado não podem usar o Plan.	Use uma conta de membro.
insufficient_scope	403	Falta à credencial o scope que este endpoint exige (tasks:read, tasks:write ou tasks:admin). A sessão iniciada e a API key pessoal de um membro não convidado podem chamar todos os endpoints, então isto significa que os scopes do Plan explícitos da linha da key não cobrem o endpoint, ou que uma key de agente ou da organização chamou um endpoint que exige uma pessoa.	Use uma API key pessoal ou uma sessão iniciada, ou adicione à key o scope que falta. Veja Autenticação e scopes do Plan.
task_archived	403	Uma tarefa arquivada não pode ser duplicada.	Restaure a tarefa primeiro e depois duplique.
update_not_author	403	Somente a pessoa autora de uma atualização de projeto pode editá-la ou anexar arquivos a ela; a pessoa autora ou um administrador da organização pode excluí-la.	Peça a quem a escreveu, ou a um administrador da organização para excluir.
view_visibility_forbidden	403	Só quem administra o quadro pode tornar uma visualização shared ou board_default, ou editá-la ou excluí-la.	Mantenha a visualização como personal, ou peça a quem administra o quadro.

404 Not Found: o objeto não existe ou não está visível para você

Código	Status	Significado	O que fazer
not_found	404	O objeto não existe, ou não está visível para você (por exemplo um projeto ou quadro members sem grant). Os dois casos retornam o mesmo corpo de propósito.	Confira o identificador. Trate como não visível, nunca como “não permitido”.

409 Conflict: a requisição entra em conflito com o estado atual

Código	Status	Significado	O que fazer
attachment_not_ready	409	O upload nunca foi concluído nem confirmado.	Conclua o upload e chame …/confirm/.
board_not_initialized	409	Falta no quadro uma coluna de que a operação precisa: não há coluna padrão para criar a tarefa, ou não há coluna done para fechá-la.	Adicione a coluna que falta ao quadro.
duplicate_board_key	409	Outro quadro já usa esta chave (chaves retiradas continuam reservadas).	Escolha outra chave.
goal_name_conflict	409	Já existe uma meta ativa com este nome.	Renomeie uma das metas.
idempotency_in_progress	409	Uma chamada com a mesma Idempotency-Key ainda está em andamento (até 120 segundos).	Aguarde e tente de novo com a mesma chave.
idempotency_key_payload_mismatch	409	A Idempotency-Key já foi usada com um corpo diferente.	Use uma chave nova para cada operação nova.
identifier_allocation_failed	409	Não foi possível alocar uma chave de tarefa (KEY-n) porque várias tarefas estavam sendo criadas ao mesmo tempo.	Tente a requisição de novo com a mesma Idempotency-Key.
label_in_use	409	A etiqueta ainda está em uso em tarefas, então não pode ser excluída.	Arquive a etiqueta com PATCH {"is_archived": true}.
last_grant_cannot_be_removed	409	Este é o último membro de um quadro ou projeto restrito aos membros.	Adicione outro membro primeiro, ou torne o item visível para toda a organização.
project_name_conflict	409	Já existe um projeto no espaço de trabalho, ativo ou arquivado, com este nome.	Escolha outro nome, ou renomeie o outro projeto.
rank_neighbor_missing	409	A tarefa after / before mudou de lugar. A resposta indica a primeira e a última tarefa atuais da coluna.	Tente de novo com uma tarefa vizinha atual.
relation_cycle	409	O vínculo criaria um ciclo.	Vincule as tarefas no sentido contrário, ou não as vincule.
relation_exists	409	As duas tarefas já estão vinculadas dessa forma.	Não é preciso fazer nada.
state_in_use	409	Ainda há tarefas ativas no estado (coluna), ou uma restauração aponta para um estado arquivado.	Envie migrate_to, ou restaure para outro estado.
version_conflict	409	A tarefa mudou desde que você a carregou. extra.current_version traz a nova versão.	Leia de novo, concilie as mudanças e tente outra vez com a nova versão.

412, 422 e 428: pré-condições e posicionamento

Código	Status	Significado	O que fazer
column_too_large	422	A coluna de destino atingiu o limite de 5.000 tarefas.	Mova ou arquive tarefas, ou divida o quadro.
precondition_failed	412	O validador If-Match de uma escrita em uma visualização salva está desatualizado.	Leia as visualizações de novo e tente outra vez com o novo ETag.
precondition_required	428	Uma escrita em uma visualização salva foi enviada sem If-Match.	Envie o ETag da sua última leitura.

501 e 503: indisponível no momento

Código	Status	Significado	O que fazer
not_implemented	501	A operação ainda não está disponível. Por exemplo, definir milestone ao criar uma tarefa: defina com PATCH depois de criar a tarefa.	Use a alternativa documentada, ou confira o changelog da API.
attachment_storage_unavailable	503	O armazenamento de arquivos está temporariamente indisponível.	Tente de novo mais tarde.
feature_temporarily_read_only	503	O Plan está temporariamente somente leitura durante um incidente. As leituras continuam funcionando, então você sempre pode exportar seu trabalho. Não é o mesmo que 402.	Tente as escritas de novo mais tarde; continue lendo normalmente.

429 Too Many Requests

Ao passar de um limite de requisições (leituras 120, escritas 60, em lote 30, feed delta 240 por minuto por ator), a API responde 429 com um header Retry-After. Aguarde esse número de segundos antes de tentar de novo. Veja Convenções do Plan.

Código	Status	Significado	O que fazer
throttled	429	Um limite de requisições para este ator foi atingido. extra.retry_after e o header Retry-After dizem quantos segundos esperar.	Espere esse tempo e tente de novo.