Codigos de error

Cuando un request a la API de TAYPI falla, la respuesta incluye un codigo de error, un mensaje descriptivo en espanol y el status HTTP correspondiente.

Formato de respuesta de error

{
    "code": "AUTH_KEY_INVALID",
    "message": "La API key proporcionada no es valida o fue revocada.",
    "http_status": 401
}

Para errores de validacion, se incluye un campo adicional errors con el detalle por campo:

{
    "code": "VALIDATION_ERROR",
    "message": "Los datos enviados no son validos.",
    "http_status": 422,
    "errors": {
        "amount": ["El monto es obligatorio."],
        "currency": ["La moneda seleccionada no es valida."]
    }
}

Errores de autenticacion

Codigo	HTTP	Mensaje
AUTH_MISSING	401	No se proporciono el header Authorization.
AUTH_INVALID_FORMAT	401	El header Authorization debe usar el formato: Bearer {api_key}.
AUTH_KEY_INVALID	401	La API key proporcionada no es valida o fue revocada.
AUTH_KEY_ENVIRONMENT	401	Estas usando una API key de sandbox en produccion, o viceversa.
AUTH_SIGNATURE_MISSING	400	No se proporciono el header Taypi-Signature.
AUTH_SIGNATURE_INVALID	403	La firma HMAC-SHA256 no es valida. Verifica tu secret key y el algoritmo de firma.
AUTH_TIMESTAMP_MISSING	400	No se proporciono el header Taypi-Timestamp.
AUTH_TIMESTAMP_EXPIRED	401	El timestamp esta fuera de la ventana permitida de 5 minutos.
AUTH_TIMESTAMP_INVALID	400	El valor de Taypi-Timestamp no es un timestamp UNIX valido.

Rate limiting

Codigo	HTTP	Mensaje
RATE_LIMIT_EXCEEDED	429	Demasiadas solicitudes. Intenta en un momento.

Idempotencia

Codigo	HTTP	Mensaje
IDEMPOTENCY_CONFLICT	409	La Idempotency-Key ya fue usada con un body diferente.

Errores de comercio

Codigo	HTTP	Mensaje
MERCHANT_INACTIVE	403	Tu cuenta de comercio esta inactiva. Contacta a soporte.
MERCHANT_TIER_INSUFFICIENT	403	Tu nivel de comercio no tiene acceso a esta funcionalidad.
MERCHANT_LIMIT_EXCEEDED	403	Has excedido tu limite mensual de transacciones.

Errores de pago

Codigo	HTTP	Mensaje
PAYMENT_NOT_FOUND	404	El pago solicitado no existe.
PAYMENT_EXPIRED	410	El pago ha expirado. Crea uno nuevo.
PAYMENT_ALREADY_COMPLETED	409	El pago ya fue completado anteriormente.
PAYMENT_INVALID_AMOUNT	422	El monto debe ser entre S/ 1.00 y el limite de tu nivel.
PAYMENT_REJECTED	422	El pago fue rechazado. Intenta de nuevo.

Errores de validacion

Codigo	HTTP	Mensaje
VALIDATION_ERROR	422	Los datos enviados no son validos.

El campo errors contiene un objeto con los campos que fallaron la validacion:

{
    "code": "VALIDATION_ERROR",
    "message": "Los datos enviados no son validos.",
    "http_status": 422,
    "errors": {
        "amount": [
            "El monto es obligatorio.",
            "El monto debe ser un numero con 2 decimales."
        ],
        "reference": [
            "La referencia no debe exceder 100 caracteres."
        ]
    }
}

Errores del procesador

Estos errores ocurren cuando hay un problema con el procesador de pagos. TAYPI traduce los errores internos a codigos genericos para no exponer detalles de la infraestructura.

Codigo	HTTP	Mensaje
PROCESSOR_CONNECTION_ERROR	502	No se pudo conectar con el procesador de pagos. Intenta en unos minutos.
PROCESSOR_TIMEOUT	504	El procesador de pagos no respondio a tiempo. Intenta de nuevo.
PROCESSOR_ERROR	502	El procesador de pagos retorno un error. Intenta de nuevo.

TIP

Si recibes errores del procesador de forma recurrente, contacta al equipo de TAYPI. Estos errores suelen ser temporales.

Errores del sistema

Codigo	HTTP	Mensaje
SERVICE_UNAVAILABLE	503	El servicio no esta disponible temporalmente. Intenta en unos minutos.
INTERNAL_ERROR	500	Error interno del servidor. Si persiste, contacta a soporte.

Tabla resumen

Codigo	HTTP	Categoria
AUTH_MISSING	401	Autenticacion
AUTH_INVALID_FORMAT	401	Autenticacion
AUTH_KEY_INVALID	401	Autenticacion
AUTH_KEY_ENVIRONMENT	401	Autenticacion
AUTH_SIGNATURE_MISSING	400	Autenticacion
AUTH_SIGNATURE_INVALID	403	Autenticacion
AUTH_TIMESTAMP_MISSING	400	Autenticacion
AUTH_TIMESTAMP_EXPIRED	401	Autenticacion
AUTH_TIMESTAMP_INVALID	400	Autenticacion
RATE_LIMIT_EXCEEDED	429	Rate limit
IDEMPOTENCY_CONFLICT	409	Idempotencia
MERCHANT_INACTIVE	403	Comercio
MERCHANT_TIER_INSUFFICIENT	403	Comercio
MERCHANT_LIMIT_EXCEEDED	403	Comercio
PAYMENT_NOT_FOUND	404	Pago
PAYMENT_EXPIRED	410	Pago
PAYMENT_ALREADY_COMPLETED	409	Pago
PAYMENT_INVALID_AMOUNT	422	Pago
PAYMENT_REJECTED	422	Pago
VALIDATION_ERROR	422	Validacion
PROCESSOR_CONNECTION_ERROR	502	Procesador
PROCESSOR_TIMEOUT	504	Procesador
PROCESSOR_ERROR	502	Procesador
SERVICE_UNAVAILABLE	503	Sistema
INTERNAL_ERROR	500	Sistema

Manejo recomendado

Errores que debes reintentar

Codigo HTTP	Estrategia
429	Espera el tiempo indicado en el header Retry-After
502, 503, 504	Reintenta con backoff exponencial (1s, 2s, 4s, max 3 intentos)

Errores que NO debes reintentar

Codigo HTTP	Accion
400	Corrige el request (headers faltantes, formato invalido)
401	Verifica tu API key y timestamp
403	Verifica tu firma HMAC o permisos de tu cuenta
404	El recurso no existe. Verifica el ID
409	Pago ya completado o conflicto de idempotencia
410	Pago expirado. Crea uno nuevo
422	Corrige los datos de entrada (validacion)
500	Error interno. Si persiste, contacta a soporte