Errores

Formato de error

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request did not pass validation.",
    "details": [
      {
        "field": "work_email",
        "issue": "Invalid email"
      }
    ],
    "request_id": "5f2c9a1b7e3d"
  }
}

• code: estable. Decide en tu código con él, nunca con message.
• message: para personas, en inglés o español (Accept-Language, o el idioma de quien creó la llave). El texto puede mejorar con el tiempo.
• details[]: errores de validación: hasta 20 elementos, cada uno con el field y el issue (siempre en inglés).
• existing_id: solo en DUPLICATE_RESOURCE: el id del registro que ya existe.
• request_id: también en el header X-Request-Id. Inclúyelo cuando contactes a soporte.

Las rutas desconocidas de la API responden un 404 en JSON, nunca una página HTML.

Códigos de error

Cada código en detalle

400 INVALID_REQUEST

• Mensaje por defecto: "La solicitud no es válida." (en inglés: "The request is invalid.")
• Cuándo: El body o un parámetro no pasó la validación (details[] lista cada campo), se envió un campo desconocido, el body no es JSON válido, Content-Type no es application/json en una escritura, el cursor es inválido o falta una Idempotency-Key obligatoria.
• Qué hacer: Lee details[] y corrige la solicitud. Los campos desconocidos se rechazan a propósito, para que un error de tipeo nunca pase en silencio.

401 INVALID_API_KEY

• Mensaje por defecto: "La llave de API falta, está mal formada, no existe o fue revocada." (en inglés: "Missing, malformed, unknown or revoked API key.")
• Cuándo: Sin header Authorization: Bearer, una llave con forma incorrecta, desconocida o revocada.
• Qué hacer: Revisa la llave en tu entorno o herramienta. Si fue revocada o se perdió, crea una nueva (Autenticación).

402 PLAN_UPGRADE_REQUIRED

• Mensaje por defecto: "La API de SpaceKru solo está disponible en planes de pago." (en inglés: "The SpaceKru API is available on paid plans only.")
• Cuándo: La cuenta no está en un plan de pago activo: plan gratuito, suscripción cancelada o impaga, un plan sin API o una cuenta cerrada. El mensaje dice cuál.
• Qué hacer: Mejora el plan o actualiza el método de pago en SpaceKru → Facturación. Las mismas llaves vuelven a funcionar enseguida.

402 AI_QUOTA_EXHAUSTED

• Mensaje por defecto: "Tu organización agotó los tokens de IA del plan y el saldo de la billetera." (en inglés: "Your organization has used all the AI tokens of its plan and its wallet balance.")
• Cuándo: Tu organización agotó los tokens de IA del plan y el saldo de su billetera.
• Qué hacer: Recarga la billetera o mejora el plan en SpaceKru → Facturación.

403 INSUFFICIENT_SCOPE

• Mensaje por defecto: "Esta llave de API no tiene el permiso necesario para esta operación." (en inglés: "This API key does not have the scope required for this operation.")
• Cuándo: La llave es válida pero le falta el permiso de la operación (una llave de solo lectura en una escritura o en /subscriptions, o una llave sin conversations en /conversations).
• Qué hacer: Usa una llave con el acceso correcto, o crea una.

403 MODULE_NOT_AVAILABLE

• Mensaje por defecto: "Tu plan no incluye el módulo que usa este endpoint." (en inglés: "Your plan does not include the module this endpoint uses.")
• Cuándo: Tu plan no incluye el módulo que usa este endpoint (crm, sales_os o scheduler).
• Qué hacer: Mejora tu plan en SpaceKru → Facturación.

404 NOT_FOUND

• Mensaje por defecto: "Recurso no encontrado." (en inglés: "Resource not found.")
• Cuándo: El id no existe en tu cuenta, pertenece a otra cuenta o no es un UUID. También para rutas desconocidas.
• Qué hacer: Revisa el id y la ruta. Los ids de otras cuentas se reportan como "no encontrado" a propósito.

409 DUPLICATE_RESOURCE

• Mensaje por defecto: "Ya existe un registro que coincide." (en inglés: "A matching record already exists.")
• Cuándo: Ya existe un lead con el mismo correo o teléfono, otro registro ya usa ese external_id, o la cotización ya se convirtió. existing_id es el registro que existe.
• Qué hacer: Usa existing_id: actualízalo si lo necesitas (upsert).

409 IDEMPOTENCY_CONFLICT

• Mensaje por defecto: "Esta Idempotency-Key ya se usó con una solicitud distinta." (en inglés: "This Idempotency-Key was already used with a different request.")
• Cuándo: La Idempotency-Key ya se usó con un body distinto, o una solicitud con la misma llave sigue en curso.
• Qué hacer: Usa una llave nueva para una solicitud distinta; si la primera sigue en curso, reintenta en unos segundos.

409 SLOT_UNAVAILABLE

• Mensaje por defecto: "Ese horario no está disponible." (en inglés: "That time slot is not available.")
• Cuándo: El horario está ocupado, el recurso está cerrado a esa hora o el grupo supera su capacidad.
• Qué hacer: Llama GET /availability y elige un horario libre.

409 CONVERSATIONS_NOT_CONFIGURED

• Mensaje por defecto: "No hay un Empleado de IA de Customer Service listo para conversar. Activa el canal Web Chat en una campaña inbound." (en inglés: "No Customer Service AI Employee is ready to chat. Turn on the Web Chat channel in an inbound campaign.")
• Cuándo: No hay un Empleado de IA de Customer Service listo para conversar: details[0].issue dice qué falta.
• Qué hacer: Completa la configuración en SpaceKru (requisitos).

413 PAYLOAD_TOO_LARGE

• Mensaje por defecto: "El cuerpo de la solicitud supera el límite de 1 MB." (en inglés: "The request body exceeds the 1 MB limit.")
• Cuándo: El body de la solicitud supera 1 MB.
• Qué hacer: Envía menos datos por solicitud.

422 UNPROCESSABLE

• Mensaje por defecto: "No se pudo procesar la solicitud." (en inglés: "The request could not be processed.")
• Cuándo: JSON válido que no se pudo aplicar: una referencia a un registro que no es tuyo (lead_id, product_id, stage_id…), una campaña que no acepta leads, un deal sin Empleado de IA para un seguimiento, una conversación cerrada, más de 50 webhooks activos o un valor que la base de datos rechazó.
• Qué hacer: Lee el mensaje: dice el campo o la regla.

429 RATE_LIMITED

• Mensaje por defecto: "Superaste el límite de solicitudes. Reintenta después del tiempo indicado en el header Retry-After." (en inglés: "Rate limit exceeded. Retry after the time indicated in the Retry-After header.")
• Cuándo: Más de 120 solicitudes en un minuto o 10,000 en un día UTC para esta llave (por defecto), o los mensajes diarios de conversaciones con IA de la cuenta.
• Qué hacer: Espera Retry-After segundos (Límites de uso).

500 INTERNAL_ERROR

• Mensaje por defecto: "Ocurrió un error inesperado." (en inglés: "An unexpected error occurred.")
• Cuándo: Algo inesperado falló de nuestro lado. Nunca se exponen detalles internos.
• Qué hacer: Reintenta con backoff. Si persiste, contáctanos con el request_id.

503 SERVICE_BUSY

• Mensaje por defecto: "La API está ocupada. Reintenta en unos segundos." (en inglés: "The API is busy. Retry in a few seconds.")
• Cuándo: El servidor está al máximo por un momento, o el modelo de IA no respondió una conversación a tiempo.
• Qué hacer: Reintenta después de Retry-After segundos (5; 15 para conversaciones con IA).

503 ELIGIBILITY_UNAVAILABLE

• Mensaje por defecto: "No pudimos verificar tu plan en este momento. Reintenta en breve." (en inglés: "We could not verify your plan right now. Please retry shortly.")
• Cuándo: No pudimos verificar tu plan por un momento. Falla cerrado: nunca es un pase libre.
• Qué hacer: Reintenta después de Retry-After segundos (10). La solicitud no se aplicó.

503 CONVERSATIONS_UNAVAILABLE

• Mensaje por defecto: "Las conversaciones por API no están disponibles en este momento." (en inglés: "AI conversations through the API are not available right now.")
• Cuándo: Las conversaciones con IA por la API están apagadas en este momento.
• Qué hacer: Reintenta más tarde.

Cómo manejar bien los errores

• Reintenta solo 429, 500 y 503, con backoff y espera aleatoria, y envía una Idempotency-Key en las creaciones para que reintentar sea seguro.
• Nunca reintentes igual un 400, 401, 402, 403, 404 o 422: la respuesta será la misma.
• Registra el request_id de cada llamada fallida. Con él encontramos exactamente qué pasó.