Errores y Códigos de Estado · Developers

La API de Dailybot retorna códigos HTTP estándar en cada respuesta. Las respuestas exitosas están en el rango 2xx; los errores de cliente en 4xx; los errores del servidor en 5xx. Todo error sigue el mismo formato: un string detail de alto nivel, un code legible por máquina y errores de validación opcionales por campo bajo errors.

Envelope de respuesta de error

Todo respuesta non-2xx es un objeto JSON con al menos un campo detail y code. Los errores de validación (respuestas 400 en endpoints de escritura) incluyen además un mapa errors por campo.

{
  "detail": "Explicación legible por humanos",
  "code": "codigo_legible_por_maquina"
}

Algunos errores incluyen campos adicionales:

• upgrade_url — presente en respuestas plan_upgrade_required, enlazando directamente a la página de upgrade de facturación
• Header Retry-After — presente en respuestas 429, indicando segundos hasta que el límite se reinicia

Siempre despachá sobre code, nunca sobre detail. El string detail es para humanos; puede cambiar. Los valores de code están congelados.

Códigos de estado de la API pública

Estado	Cuándo lo recibes	Cómo recuperarte
200 OK	GET, PATCH o POST exitoso que retorna el recurso.	Nada — éxito.
201 Created	POST exitoso que crea un nuevo recurso.	El recurso está en el cuerpo; nota el uuid.
202 Accepted	Solicitud aceptada para procesamiento asíncrono.	Sondea o suscríbete a un webhook.
204 No Content	DELETE o PATCH exitoso sin cuerpo de respuesta.	Sin cuerpo — éxito.
400 Bad Request	Error de validación. El campo code tiene detalles.	Corrige el payload y reintenta. Nunca reintentes a ciegas.
401 Unauthorized	Credencial faltante, expirada o inválida.	Confirma tu API key o refresca tu sesión CLI con dailybot login.
403 Forbidden	La credencial es válida pero el llamante no tiene permiso. Ver code.	Revisa el campo code y la matriz de autenticación.
404 Not Found	El recurso no existe o el llamante no puede verlo.	Verifica el UUID y el alcance de la credencial.
409 Conflict	El write entra en conflicto con el estado actual.	Relee el recurso, elige el siguiente estado correcto, reintenta.
422 Unprocessable Entity	El payload es sintácticamente válido pero semánticamente inválido.	Lee detail — identifica el campo ofensivo.
429 Too Many Requests	Límite de rate excedido.	Respeta el header Retry-After. Ver /es/developers/rate-limits.
500 Internal Server Error	Error inesperado del lado de Dailybot.	Reintenta con backoff exponencial.
502 / 503 / 504	Interrupción upstream o ventana de mantenimiento.	Reintenta con backoff exponencial.

Política de reintentos

Reintenta solo en 429, 502, 503, 504 y 5xx idempotentes. Nunca reintentes un 4xx a ciegas — el error es de tu lado. Para 429, respeta Retry-After; para 5xx, usa backoff exponencial (empieza en 250 ms, máximo 30 s, añade jitter).

Códigos de error legibles por máquina

Toda respuesta de plan-gate, capability-gate o rate-limit lleva un campo code estable junto al detail legible por humanos. Despachá sobre code, nunca parsees la prosa.

Garantía de estabilidad: Los valores de code listados aquí están congelados — los valores existentes nunca cambiarán de significado ni serán reutilizados.

Códigos de autenticación y plan

code	HTTP	Cuándo lo recibes
invalid_credentials	403	Las credenciales no resuelven a una key o token válido
api_key_owner_inactive	403	El propietario de la API key está desactivado
plan_free_api_keys_forbidden	403	La organización de la API key está en el plan gratuito
plan_missing_core_api_integrations	403	El plan de la org no incluye acceso a la API
plan_upgrade_required	403	Token CLI Bearer de plan gratuito en endpoint no allowlisted
free_plan_daily_limit_exceeded	429	Límite diario del plan gratuito alcanzado
org_admin_required	403	La acción requiere rol de admin de la organización
member_in_scope_required	403	El usuario destino no está en la misma organización

Códigos de gestión de API keys

code	HTTP	Cuándo lo recibes
agent_key_admin_only	400	Un no-admin intentó crear una agent key
target_user_inactive	400	El usuario destino para la creación de key está desactivado
target_user_not_found	400	UUID de usuario destino no encontrado en la organización

Códigos de mensajería

code	HTTP	Cuándo lo recibes
send_as_user_conflict	400	send_as_user combinado con bot_username, bot_icon_url o bot_icon_emoji
send_as_user_invalid_uuid	400	Formato UUID inválido en send_as_user
send_as_user_not_found	400	Usuario no encontrado, inactivo o en una org diferente
cli_send_message_target_not_allowed	403	Llamante CLI intentó enviar mensaje a un destino fuera de alcance

Códigos de filtros y query

code	HTTP	Cuándo lo recibes
search_query_too_long	400	?search= excede 256 caracteres. Aplica de forma uniforme 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 o ?end_date no es una fecha válida YYYY-MM-DD, o start_date > end_date. Aplica a todo endpoint que acepta start_date / end_date.
invalid_user_identifier	400	?user= no es un UUID válido. Usa el UUID del usuario de GET /v1/users/. Aplica a /v1/checkins/{uuid}/responses/ y /v1/forms/{uuid}/responses/.
not_valid_kudos_filter	400	Alias deprecado — usa invalid_kudos_filter.
invalid_kudos_filter	400	?filter= no es uno de kudos_received / kudos_given (sin distinción de mayúsculas). Aplica a /v1/kudos/ y /v1/kudos/organization/.
invalid_sender_uuid	400	?sender_uuid= no es un UUID válido. Aplica a /v1/kudos/ y /v1/kudos/organization/.
invalid_receiver_uuid	400	?receiver_uuid= no es un UUID válido. Aplica a /v1/kudos/ y /v1/kudos/organization/.
invalid_workflow_state	400	?state= no es un estado de workflow válido para el form. Aplica a /v1/forms/{uuid}/responses/.
form_response_view_all_forbidden	403	Un miembro usó ?all=true en un form del que no puede ver todas las respuestas.

Respuestas de error en JSON: Toda respuesta de error de /v1/** está garantizada como application/json — la API nunca devuelve páginas HTML de error para fallas de validación de entrada del cliente.

Códigos de autoría (forms y check-ins)

code	HTTP	Cuándo lo recibes
unknown_field	400	El cuerpo contiene una clave no reconocida en endpoints de configuración
questions_required	400	Create llamado sin al menos una pregunta
short_question_required	400	Pregunta sin short_question y sin generate_short_question
checkin_requires_participant	400	Crear check-in con cero participantes
anonymous_irreversible	400	Intento de deshabilitar anonimato en un check-in anónimo
report_channel_not_found	400	report_channels contiene un ID no en GET /v1/report-channels/
too_many_report_channels	400	Más de 3 canales de reporte provistos
question_uuids_incomplete	400	Reorder sin todos los UUIDs de preguntas

Endpoints solo para admin

Los miembros que no son admin reciben 403 con code: "org_admin_required" en estos 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 (solo create)