Errores

Todas las respuestas de error siguen el mismo formato:

{
  "error": "code_machine_readable",
  "message": "Descripcion humana del problema",
  "details": { /* opcional, contexto adicional */ }
}

El campo error es un slug en snake_case estable: tu codigo puede hacer match contra el. El message es para humanos y puede cambiar entre versiones.

Codigos comunes

Autenticacion - 401 / 403

error	Causa
unauthorized	Cabecera Authorization ausente o malformada
invalid_key	La API key no existe, esta revocada o expirada
forbidden_scope	Usaste publica donde se exige privada (o viceversa)
tenant_mismatch	La key pertenece a otro tenant distinto al de la URL

Validacion - 400

error	Causa
missing_query	Falta q en /search
invalid_filter	Sintaxis de filter incorrecta
query_too_long	q supera 200 chars
invalid_payload	El JSON del body no valida contra el schema
unknown_data_source	El source no existe en el tenant

Recursos - 404

error	Causa
tenant_not_found	El slug del tenant no existe
not_found	El recurso solicitado no existe (sinonimo, regla, item, etc.)

Conflictos - 409

error	Causa
synonym_exists	Ya existe un sinonimo con ese word en este data source
idempotency_replayed	Reuso de Idempotency-Key con payload distinto al original

Rate limiting - 429

error	Causa
rate_limited	Has superado el rate limit. Cabecera Retry-After en segundos

Errores internos - 5xx

error	Causa
internal_error	Bug inesperado. Si persiste, contacta soporte con el request_id de la respuesta
engine_unavailable	El motor de busqueda no responde. Suele resolverse en segundos
degraded	Mibizum opera en modo degradado (e.g. cache solo)

Comportamiento ante errores

Recomendaciones:

• 429: respeta Retry-After. No martillees con backoff exponencial brusco.
• 5xx: reintenta con backoff exponencial (e.g. 1s, 2s, 4s, max 3 reintentos). Si tras 3 sigue, propaga el fallo a tu usuario.
• 4xx distintos de 429: no reintentes. El fallo es deterministico, el retry da el mismo resultado.

Logs y diagnostico

Cada respuesta lleva en la cabecera:

X-Request-Id: req_a1b2c3d4...

Adjunta ese X-Request-Id a cualquier ticket de soporte para acelerar el diagnostico.