Erros e Códigos de Status · Developers

A API do Dailybot retorna códigos HTTP padrão em cada resposta. Respostas bem-sucedidas ficam na faixa 2xx; erros do cliente em 4xx; erros do servidor em 5xx. Todo erro segue o mesmo formato: um string detail de alto nível, um code legível por máquina e erros de validação opcionais por campo sob errors.

Envelope de resposta de erro

Toda resposta non-2xx é um objeto JSON com no mínimo um campo detail e code. Erros de validação (respostas 400 em endpoints de escrita) incluem adicionalmente um mapa errors por campo.

{
  "detail": "Explicação legível por humanos",
  "code": "codigo_legivel_por_maquina"
}

Alguns erros incluem campos adicionais:

• upgrade_url — presente em respostas plan_upgrade_required, com link direto para a página de upgrade de faturamento
• Header Retry-After — presente em respostas 429, indicando segundos até o limite ser redefinido

Sempre despache sobre code, nunca sobre detail. O string detail é para humanos; pode mudar. Os valores de code são congelados.

Códigos de status da API pública

Status	Quando você recebe	Como se recuperar
200 OK	GET, PATCH ou POST bem-sucedido que retorna o recurso.	Nada — sucesso.
201 Created	POST bem-sucedido que cria um novo recurso.	O recurso está no corpo; anote o uuid.
202 Accepted	Solicitação aceita para processamento assíncrono.	Faça poll ou assine um webhook.
204 No Content	DELETE ou PATCH bem-sucedido sem corpo de resposta.	Sem corpo — sucesso.
400 Bad Request	Erro de validação. O campo code tem detalhes.	Corrija o payload e tente novamente. Nunca faça retry às cegas.
401 Unauthorized	Credencial ausente, expirada ou inválida.	Confirme sua API key ou atualize sua sessão CLI com dailybot login.
403 Forbidden	A credencial é válida mas o chamador não tem permissão. Veja code.	Verifique o campo code e a matriz de autenticação.
404 Not Found	O recurso não existe ou o chamador não pode vê-lo.	Verifique o UUID e o escopo da credencial.
409 Conflict	O write conflita com o estado atual.	Releia o recurso, escolha o próximo estado correto, tente novamente.
422 Unprocessable Entity	O payload é sintaticamente válido mas semanticamente inválido.	Leia detail — identifica o campo ofensivo.
429 Too Many Requests	Limite de rate excedido.	Respeite o header Retry-After. Ver /pt/developers/rate-limits.
500 Internal Server Error	Erro inesperado do lado do Dailybot.	Tente novamente com backoff exponencial.
502 / 503 / 504	Interrupção upstream ou janela de manutenção.	Tente novamente com backoff exponencial.

Política de retry

Faça retry apenas em 429, 502, 503, 504 e 5xx idempotentes. Nunca faça retry de um 4xx às cegas — o erro é do seu lado. Para 429, respeite Retry-After; para 5xx, use backoff exponencial (comece em 250 ms, máximo 30 s, adicione jitter).

Códigos de erro legíveis por máquina

Toda resposta de plan-gate, capability-gate ou rate-limit carrega um campo code estável junto ao detail legível por humanos. Despache sobre code, nunca faça parse da prosa.

Garantia de estabilidade: Os valores de code listados aqui são congelados — valores existentes nunca mudarão de significado nem serão reutilizados.

Códigos de autenticação e plano

code	HTTP	Quando você recebe
invalid_credentials	403	As credenciais não resolvem para uma key ou token válido
api_key_owner_inactive	403	O proprietário da API key está desativado
plan_free_api_keys_forbidden	403	A organização da API key está no plano gratuito
plan_missing_core_api_integrations	403	O plano da org não inclui acesso à API
plan_upgrade_required	403	Token CLI Bearer de plano gratuito em endpoint não allowlisted
free_plan_daily_limit_exceeded	429	Limite diário do plano gratuito atingido
org_admin_required	403	A ação requer papel de admin da organização
member_in_scope_required	403	O usuário alvo não está na mesma organização

Códigos de gerenciamento de API keys

code	HTTP	Quando você recebe
agent_key_admin_only	400	Um não-admin tentou criar uma agent key
target_user_inactive	400	O usuário alvo para criação de key está desativado
target_user_not_found	400	UUID do usuário alvo não encontrado na organização

Códigos de mensagens

code	HTTP	Quando você recebe
send_as_user_conflict	400	send_as_user combinado com bot_username, bot_icon_url ou bot_icon_emoji
send_as_user_invalid_uuid	400	Formato UUID inválido em send_as_user
send_as_user_not_found	400	Usuário não encontrado, inativo ou em org diferente
cli_send_message_target_not_allowed	403	Chamador CLI tentou enviar mensagem para um destino fora de escopo

Códigos de filtros e query

code	HTTP	Quando você recebe
search_query_too_long	400	?search= excede 256 caracteres. Aplica-se uniformemente a /v1/forms/, /v1/checkins/, /v1/forms/{uuid}/responses/, /v1/checkins/{uuid}/responses/, /v1/kudos/, /v1/workflows/, /v1/users/.
invalid_date_range	400	?start_date ou ?end_date não é uma data válida YYYY-MM-DD, ou start_date > end_date. Aplica-se a todo endpoint que aceita start_date / end_date.
invalid_user_identifier	400	?user= não é um UUID válido. Use o UUID do usuário obtido em GET /v1/users/. Aplica-se a /v1/checkins/{uuid}/responses/ e /v1/forms/{uuid}/responses/.
not_valid_kudos_filter	400	Alias depreciado — use invalid_kudos_filter.
invalid_kudos_filter	400	?filter= não é um de kudos_received / kudos_given (sem distinção de maiúsculas). Aplica-se a /v1/kudos/ e /v1/kudos/organization/.
invalid_sender_uuid	400	?sender_uuid= não é um UUID válido. Aplica-se a /v1/kudos/ e /v1/kudos/organization/.
invalid_receiver_uuid	400	?receiver_uuid= não é um UUID válido. Aplica-se a /v1/kudos/ e /v1/kudos/organization/.
invalid_workflow_state	400	?state= não é um estado de workflow válido para o form. Aplica-se a /v1/forms/{uuid}/responses/.
form_response_view_all_forbidden	403	Um membro usou ?all=true em um form que não tem permissão para ver todas as respostas.

Respostas de erro em JSON: Toda resposta de erro de /v1/** é garantida como application/json — a API nunca retorna páginas HTML de erro para falhas de validação de entrada do cliente.

Códigos de autoria (forms e check-ins)

code	HTTP	Quando você recebe
unknown_field	400	O corpo contém uma chave não reconhecida em endpoints de configuração
questions_required	400	Create chamado sem ao menos uma pergunta
short_question_required	400	Pergunta sem short_question e sem generate_short_question
checkin_requires_participant	400	Criar check-in com zero participantes
anonymous_irreversible	400	Tentativa de desabilitar anonimato em um check-in anônimo
report_channel_not_found	400	report_channels contém um ID não em GET /v1/report-channels/
too_many_report_channels	400	Mais de 3 canais de reporte fornecidos
question_uuids_incomplete	400	Reorder sem todos os UUIDs de perguntas

Endpoints apenas para admin

Membros que não são admin recebem 403 com code: "org_admin_required" nestes endpoints:

Endpoint	Métodos
/v1/kudos/organization/	GET
/v1/webhook-subscription/	POST, DELETE
/v1/webhook-subscription/sample/	POST
/v1/open-conversation/	POST
/v1/teams/{uuid}/members/{uuid}/	GET, PUT, PATCH, DELETE
/v1/teams/{uuid}/invite/	POST
/v1/followups/	POST (apenas create)