Errors

Todos los errores públicos siguen esta forma:

{
  "error": "tsuzuro/validation/invalid_request",
  "message": "Request validation failed.",
  "requestId": "req_...",
  "docsUrl": "https://docs.tsuzuro.com/errors/validation",
  "details": {}
}

Reglas

• requestId siempre existe.
• error usa namespace tsuzuro/<area>/<reason>.
• No se exponen stack traces ni IDs internos.
• details puede omitirse si no hay información accionable.
• docsUrl apunta a esta sección o a una página dedicada (/errors/auth, /errors/validation).

SDK

El SDK mapea respuestas de error a:

• TsuzuroAuthError
• TsuzuroValidationError
• TsuzuroRateLimitError
• TsuzuroApiError

Catálogo

Auth

Ver también Errors / Auth.

Código	HTTP típico	Qué significa
tsuzuro/auth/missing_credentials	401	Falta Bearer token o cookie de refresh.
tsuzuro/auth/insufficient_scope	403	La API key o el token no tiene el scope requerido.
tsuzuro/auth/expired_token	401	Access o refresh token expirado.
tsuzuro/auth/invalid_token	401	Token inválido, revocado o mal formado.
tsuzuro/auth/invalid_api_key	401	API key inválida o revocada.
tsuzuro/auth/signup_disabled	403	Signup público deshabilitado en este entorno.
tsuzuro/auth/email_domain_not_allowed	422	Dominio de email bloqueado (desechable u allowlist).
tsuzuro/auth/email_in_use	409	Email ya registrado.
tsuzuro/auth/invalid_credentials	401	Email o password incorrectos.
tsuzuro/auth/no_workspace	403	Usuario sin membership de workspace.
tsuzuro/auth/email_not_verified	403	Email sin verificar; recursos live bloqueados.
tsuzuro/auth/login_required	401	La acción requiere sesión autenticada (p. ej. aceptar invitación).

Validation

Ver también Errors / Validation.

Código	HTTP típico	Qué significa
tsuzuro/validation/invalid_request	400/422	Body/query/path no pasa el schema Zod.

Runtime

Código	HTTP típico	Qué significa
tsuzuro/runtime/not_found	404	Recurso inexistente o fuera de tu tenant scope.
tsuzuro/runtime/internal_error	500	Error inesperado. Reintenta con el requestId.
tsuzuro/runtime/invalid_request	400	Request inválido fuera del schema de validación.
tsuzuro/runtime/idempotency_conflict	409	Misma Idempotency-Key con payload distinto.
tsuzuro/runtime/missing_idempotency_key	400	Falta Idempotency-Key en un write crítico.
tsuzuro/runtime/conflict	409	Conflicto de estado (p. ej. invitación duplicada).

Rate limit

Código	HTTP típico	Qué significa
tsuzuro/rate_limit/exceeded	429	Cuota excedida. Respeta Retry-After.

Console

Código	HTTP típico	Qué significa
tsuzuro/console/not_found	404	Proyecto/recurso de Console no encontrado.
tsuzuro/console/forbidden	403	Sin membership de Console en el proyecto.

WhatsApp

Código	HTTP típico	Qué significa
tsuzuro/whatsapp/invalid_verify_token	401	hub.verify_token no coincide.
tsuzuro/whatsapp/invalid_signature	401	Firma x-hub-signature-256 inválida.
tsuzuro/whatsapp/connect_failed	422	Falló el connect (token/WABA/phone).

Meta app

Código	HTTP típico	Qué significa
tsuzuro/meta_app/in_use	409	No puedes revocar: hay channels WhatsApp usando la app.

Agent runs

Código	HTTP típico	Qué significa
tsuzuro/agent_runs/suggestion_already_resolved	409	La sugerencia suggest ya fue aprobada/editada/descartada.