Errores

Todos los errores, en todos los endpoints, usan un único envoltorio:

{
  "error": {
    "code": "not_found",
    "message": "Link not found",
    "doc_url": "https://linkprofit.com/docs/api/errors"
  }
}

Ramifica según error.code y muestra error.message a las personas. Los errores de validación añaden un array details con mensajes por campo:

{
  "error": {
    "code": "validation_failed",
    "message": "Request failed validation",
    "doc_url": "https://linkprofit.com/docs/api/errors",
    "details": [
      { "path": "url", "message": "Destination URL is not a valid address" }
    ]
  }
}

Códigos de error

| Código | HTTP | Significado | Qué hacer | |---|---|---|---| | unauthorized | 401 | Clave ausente, desconocida, revocada o caducada | Revisa la cabecera; emite una clave nueva | | forbidden | 403 | Tipo de clave incorrecto para el endpoint, o la operación no está permitida | Usa una clave de espacio de trabajo o de partner según la documentación | | insufficient_scope | 403 | A la clave le falta un alcance obligatorio | Crea una clave con el alcance indicado en el mensaje | | plan_restricted | 403 | El plan no incluye esta capacidad | Sube de plan o quita esa función de la solicitud | | not_found | 404 | El recurso no existe, o pertenece a otro tenant | Verifica el id; los recursos ajenos son indistinguibles de los inexistentes | | invalid_request | 400 | JSON mal formado, cursor incorrecto, regla de negocio incumplida | Corrige la solicitud | | validation_failed | 422 | El cuerpo o la consulta no pasan la validación del esquema | Corrige los campos listados en details | | conflict | 409 | Conflicto de estado: slug ocupado, Idempotency-Key reutilizada con otro cuerpo | Elige otro valor o una clave de idempotencia nueva | | quota_exceeded | 422 | Se ha agotado una cuota del plan (enlaces, dominios, clientes) | Sube de plan o libera cuota | | rate_limited | 429 | Demasiadas solicitudes con esta clave | Espera los segundos de Retry-After; ver Límites de solicitudes | | not_configured | 503 | La capacidad no está configurada en este entorno | Reinténtalo más tarde o contacta con soporte | | internal | 500/502/504 | Error inesperado de la plataforma | Reintenta con espera creciente; avisa si persiste | | invalid_click_id | 422 | El click_id está falsificado, manipulado o se emitió en otro espacio de trabajo | Envía el valor del parámetro del identificador de clic tal cual aparecía en la dirección de destino | | attribution_expired | 422 | El clic es más antiguo que la ventana de atribución del espacio de trabajo | No hay nada que reintentar; ajusta la ventana en el panel si hace falta |

Reglas de tratamiento que compensan

• Un 404 también es aislamiento. Un id de otro espacio de trabajo responde not_found, nunca forbidden: la API no revela si un id ajeno existe.
• Reintenta solo lo que sea seguro. Reintenta internal y rate_limited con espera creciente. No reintentes a ciegas conflict ni validation_failed: la solicitud en sí está mal. Usa Idempotency-Key para que reintentar una mutación sea seguro.
• GET /links nunca devuelve 404. Los filtros vacíos devuelven una lista vacía; un 404 sobre la colección sería ambiguo.