Errores

La API usa códigos de estado HTTP estándar y retorna cuerpos de error en JSON.

Códigos de Estado HTTP

Formato de Respuesta de Error

La API retorna errores en el siguiente formato:

{
  "message": "Checkout Inválido",
  "errors": {
    "items": ["can't be blank"]
  }
}

El campo message siempre está presente. El objeto errors es opcional y contiene detalles de validación a nivel de campo.

Errores Comunes

Autenticación Fallida

// 401
{
  "message": "Autenticación Errónea 👀",
  "errors": {
    "authentication": [
      "Las llaves de API son inválidas o no coinciden."
    ]
  }
}

Tus llaves de API son inválidas, faltan, o no coinciden con la misma cuenta/ambiente.

Si envías una llave sk_test_ que ya no existe, el mensaje en errors.authentication es: “Esta llave TEST no existe. Las cuentas LIVE ya no tienen llave TEST: las llaves TEST ahora viven en un Sandbox. Ábrelo en Configuración → Llaves API → Sandbox y usa su llave TEST.” Las cuentas de producción ya no tienen llave TEST; crea una dentro de un Sandbox.

Una llave cuyo ambiente no coincide con el de su cuenta responde 401 con "code": "environment_mismatch".

Error de Validación

// 400
{
  "message": "Producto Inválido",
  "errors": { "name": ["can't be blank"] }
}

Los parámetros proporcionados no pasan la validación. Revisa el objeto errors para detalles específicos.

No Se Puede Modificar Checkout Pagado

// 422
{ "message": "No se puede modificar un checkout pagado" }

Intentaste modificar un checkout que ya ha sido pagado.

Recurso No Encontrado

// 404
{ "message": "Producto no encontrado" }

El recurso solicitado no existe o no pertenece a tu cuenta.

Límites de Tasa

Cada llave secreta tiene un presupuesto de ráfaga de 60 solicitudes por segundo, independiente de la dirección IP desde la que llamas. Solo en /api/users aplica además un límite de 300 solicitudes cada 5 minutos por dirección IP, y las llaves sk_test_ tienen un tope adicional de 300 solicitudes cada 5 minutos por llave en esa ruta. Las variantes de formato, como /api/users.json, comparten esos presupuestos. Los demás endpoints, incluidos /api/checkouts, /api/products y /api/customers, conservan el límite de ráfaga de 60 solicitudes por segundo por llave, sin esos topes de cinco minutos.

Al exceder un límite la API responde 429 con el header Retry-After en segundos. Espera ese tiempo antes de reintentar y usa espera exponencial si el 429 se repite.

HTTP/2 429 Too Many Requests
Retry-After: 1

Un 503 con cuerpo Blocked no es este throttle: corresponde a una regla de bloqueo de seguridad y no se resuelve esperando el Retry-After. Comparte con soporte la hora y el identificador de la petición para identificar la regla.

Manejo de Errores

Siempre verifica el código de estado HTTP antes de procesar la respuesta:

if (response.status >= 400) {
  const error = await response.json();
  console.error('Error de API:', error.message);
  
  // Manejar errores de validación específicos
  if (error.errors) {
    Object.keys(error.errors).forEach(field => {
      console.error(`${field}: ${error.errors[field].join(', ')}`);
    });
  }
}

Diagnosticar tu Sandbox

Antes de probar un ID, llama GET /test con la misma llave y confirma environment: sandbox. Un ID de otra cuenta o ambiente no se puede reutilizar. sandbox_unsupported indica una operación bloqueada. Una llave enmascarada no autentica: crea una llave nueva o rota la anterior si deseas revocarla. Consulta el diagnóstico de primer pago.