Errores

Los errores siguen JSON:API: application/vnd.api+json con una lista errors. Un error de validación trae un elemento por campo y source.pointer indica cuál.

422 — validación

{
  "errors": [
    {
      "status": "422",
      "title": "Validación fallida",
      "detail": "'amount': debe ser mayor que cero.",
      "source": { "pointer": "/data/attributes/amount" }
    }
  ]
}

404 — no encontrado

{
  "errors": [
    {
      "status": "404",
      "title": "No encontrado",
      "detail": "PaymentLink '00000000-0000-0000-0000-000000000000' no encontrado.",
      "source": null
    }
  ]
}

Códigos HTTP

Código	Cuándo
201 / 200	Creado / correcto.
401	Falta el token, está vencido o su emisor no es el esperado. Responde con la cabecera WWW-Authenticate: Bearer y sin cuerpo.
403	Token válido pero sin permiso (rol insuficiente o IP no permitida), o funcionalidad deshabilitada.
404	El recurso no existe (o no es accesible para tu comercio).
409	El estado del recurso no admite la operación (por ejemplo, revocar un link ya pagado).
422	Validación fallida; revisa source.pointer.

info

No hay un catálogo de códigos de error propios (code): hoy se distingue por status, title y source.pointer. Los mensajes detail están en español.

Qué hacer ante un error

• 401: pide un token nuevo; los tokens duran pocos minutos (expires_in). Si persiste con The issuer … is invalid, estás pidiendo el token en una dirección de Keycloak distinta de la pública; ver autenticación.
• 422: corrige el campo indicado; no reintentes igual.
• 5xx o cortes de red: reintenta con espera creciente. Ojo: la API pública no tiene Idempotency-Key, así que reintentar una creación puede duplicar el link; lista antes de reintentar. Ver límites.