Conceptos
Errores El catálogo de errores 4xx con casos concretos relevantes para partners.
Las APIs de Skip usan códigos HTTP estándar. Esta página lista los códigos que efectivamente vas a encontrar, con la causa y la recuperación de cada uno.
Causa Ejemplo Recuperación Error de validación Falta customer.email en POST /orders Arregla el body. Restricción a nivel campo total_amount es negativoArregla el body. provider_data desde un no-meta-providerLlamando /api/spot/widget con provider_data cuando tu cuenta no está marcada Quítalo, o pide a Skip habilitar modo meta-prestador. Probe de readiness del widget POST /orders/{hash}/payment con códigos como processor_customer_identity_not_validatedEl widget lo gestiona — tú no. Ver Caso borde del widget AAPD .
Causa Ejemplo Recuperación Credencial faltante o errónea Sin header Authorization en POST /orders Agrégalo. Tipo de credencial errado Enviando client_id a un endpoint que necesita client_secret Cambia a la credencial correcta. Provider inactivo Tu public_key apunta a un Provider con is_active=false Contacta ops. Ambiente equivocado Enviando pk_test_* a producción Usa la clave de producción.
Causa Ejemplo Recuperación Falta scope Llamando POST /api/spot/sacmed/centers sin scope cnpl.meta_prestador Pide a Skip agregar el scope.
Causa Ejemplo Recuperación Hash de orden desconocido GET /orders/ord_unknownConfirma el hash. Beneficiario no existe por RUT POST /api/spot/gastos?rut=... para un RUT sin beneficiario SkipEl paciente no es usuario Skip. Onboardéalo primero vía Spot, o salta el envío. Widget token no existe El paciente abrió un link viejo Mintea un token nuevo.
Causa Ejemplo Recuperación Reference de orden duplicada POST /orders con una reference que ya existeUsa reference única por intento. Colisión de RUT POST /api/spot/user para un RUT registrado bajo otro correoMuéstrale al paciente el flujo de recuperación (ver Casos borde del widget Spot ).
Causa Ejemplo Recuperación Widget token expirado El paciente volvió después del TTL de 1 hora Mintea un token nuevo, o usa long_term_token=true para extender a 30 días.
Causa Ejemplo Recuperación RUT mal formado 12345678 (sin dígito verificador)Normaliza y reenvía. Ver RUT . Formato de CI inválido Validate-identity con un serial mal formado Recolecta de nuevo del paciente. Ventipay rechazó la identidad Mismatch con registros nacionales El paciente debe contactar ISAPRE / registro nacional. Skip no puede saltarse esto.
Todas las respuestas de error de Skip tienen este shape:
{ "error" : "invalid_credential" , "message" : "Explicación legible." , "details" : { /* opcional, específico al código */ } } error es un código machine-readable estable. Hazle match en tu manejo de errores. message es solo para humanos — su redacción cambia.
Las respuestas 5xx son problemas server-side del lado Skip. Son raros. Reintenta con backoff (ver la política de retries que usa SkipPay internamente). Si los 5xx persisten más de ~5 minutos, escala a ops por Slack o correo.
