> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manejo de errores

Una gestión eficaz de los errores es fundamental para crear integraciones sólidas con la API de Localpayment. Comprender los diferentes tipos de errores y sus códigos correspondientes te ayudará a diagnosticar problemas rápidamente e implementar las soluciones adecuadas.

Ofrecemos una gestión integral de errores mediante códigos de estado HTTP estandarizados y respuestas de error detalladas. Esta guía te muestra cómo gestionar los errores de forma eficaz para crear una integración más robusta y fácil de usar.

## Descripción general

Una gestión de errores adecuada es fundamental para crear integraciones de pago fiables. Localpayment utiliza una estructura de errores coherente en todos los endpoints de la API para ayudarte a identificar y resolver problemas rápidamente.

> [card] [Códigos estandarizados](#http-response-codes)
>
> Códigos de error consistentes en todos los endpoints de la API y métodos de pago.

> [card] [Mensajes detallados](#error-response-structure)
>
> Descripciones legibles para humanos con detalles específicos sobre los errores.

> [card] [Mejores prácticas](#best-practices-for-error-handling)
>
> Estrategias comprobadas para gestionar errores en entornos de producción.

***

## Códigos de respuesta HTTP

Localpayment utiliza códigos de estado HTTP estándar para indicar el éxito o el fracaso de las solicitudes de API:​

| Código HTTP | Estado | Descripción |
| - | - | - |
| 200 | `OK` | La solicitud se realizó correctamente y la respuesta contiene los datos solicitados. |
| 201 | Creado | El recurso se creó correctamente (por ejemplo, se inició un nuevo pago). |
| 400 | Solicitud incorrecta | La solicitud estaba mal formulada, contenía parámetros no válidos o le faltaban campos obligatorios. |
| 401 | No autorizado | Falló la autenticación, las credenciales no son válidas o falta/ha caducado el token de acceso. |
| 403 | Prohibido | Se entiende la solicitud, pero ha sido denegada por falta de permisos. |
| 404 | No encontrado | No se pudo encontrar el recurso solicitado (por ejemplo, endpoint o ID de transacción no válidos). |
| 409 | Conflicto | La solicitud entra en conflicto con el estado actual del recurso (por ejemplo, transacción duplicada). |
| 429 | Demasiadas peticiones | Se ha superado el límite de solicitudes. Se han realizado demasiadas solicitudes en un período de tiempo determinado. |
| 500 | Error interno del servidor | Se ha producido un error inesperado en los servidores de Localpayment. |

***

## Estructura de respuesta de error

Cuando se produce un error, Localpayment devuelve un objeto JSON con información detallada sobre el error:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "status": {
    "code": "300",
    "description": "REJECTED",
    "detail": "Invalid param + [paymentMethod] + [Is mandatory]"
  },
  "errors": [
    {
      "code": "300",
      "description": "REJECTED",
      "detail": "Invalid param + [paymentMethod] + [Is mandatory]"
    }
  ]
}
```

### Campos de respuesta de error

| Campo | Tipo | Descripción | Ejemplo |
| - | - | - | - |
| `status.code` | string | Código de estado específico de Localpayment | `300` |
| `status.description` | string | Breve descripción del error | `REJECTED` |
| `status.detail` | string | Mensaje de error detallado | `Invalid param [paymentMethod]` |
| errors\[] | array | Arreglo de objetos de error específicos | Véase a continuación |
| errors\[].code | string | Código de error específico de Localpayment | `300` |

***

## Referencia de códigos de estado internos

Aunque Localpayment utiliza códigos HTTP estándar para el estado a nivel de solicitud, los campos `status.code` y `errors[].code` proporcionan un estado detallado de la lógica de negocio y del procesamiento.

| Rango de códigos | Categoría | Significado semántico | Escenarios de ejemplo |
| - | - | - | - |
| **1xx** | Pendiente | La transacción se ha iniciado, pero está pendiente de confirmación o actuación final. | `100` (Pendiente), `103` (Aprobado pero no acreditado) |
| **2xx** | Éxito | La transacción se ha procesado y completado con éxito. | `200` (Completado) |
| **3xx** | Validación | La solicitud falló debido a parámetros faltantes o no válidos. | `300` (Parámetro no válido), `301` (No autorizado para el país) |
| **7xx** | Lógica empresarial | La transacción fue rechazada debido a normas bancarias o comerciales. | `701` (Cuenta no válida), `702` (Fondos insuficientes) |
| **8xx** | Sistema/Proveedor | La transacción fue rechazada por el proveedor subyacente o por un error interno del sistema. | `801` (Error de parámetros), `802` (Rechazado por el proveedor) |
| **9xx** | Reversión/Negativo | La transacción ha sido revertida, reembolsada o impugnada. | `902` (Reembolsado), `906` (Contracargo) |

***

## Escenarios de errores comunes

### Errores de autenticación

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "detail": "Given token not valid for any token type",
  "code": "token_not_valid",
  "messages": [
    {
      "token_class": "AccessToken",
      "token_type": "access",
      "message": "Token is invalid or expired"
    }
  ]
}
```

> [!NOTE]
>
> **Solución**
>
> Verifica tus credenciales de API y asegúrate de que tu token de acceso sea válido. Si es necesario, utiliza el endpoint de actualización de token.

### Errores de validación

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "46014bdc-c3a7-1b15-8dcf-c7050c1c8199",
  "internalId": "caa4e9aa-f634-497c-ba75-7f88b005ca62",
  "status": {
    "code": "801",
    "description": "REJECTED",
    "detail": "Params error"
  },
  "errors": [
    {
      "code": "300",
      "detail": "Invalid param + [paymentMethod] + doesn't exist for MEX"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.bank.account.[number, type | alias]] + must not be null"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.document.type] + is invalid for country MEX"
    },
    {
      "code": "300",
      "detail": "Invalid param + [payer.document] + is invalid for payer type"
    },
    {
      "code": "701",
      "detail": "IncorrectAccountNumber"
    }
  ]
}
```

> [!NOTE]
>
> **Solución**
>
> Revisa el arreglo `errors` para ver los problemas de validación de campos específicos. Consulta la documentación de la API para conocer los campos obligatorios y las especificaciones de formato.

### Errores de lógica empresarial

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "8c0b537a-e907-4d87-93db-5dab9807e093",
  "internalId": "dddfde6c-b61c-4b0e-8916-d88886133c4d",
  "status": {
    "code": "701",
    "description": "REJECTED"
  },
  "errors": [
    {
      "code": "701",
      "detail": "Invalid bank account number. Account number verification failed."
    }
  ]
}
```

> [!NOTE]
>
> **Solución**
>
> Estos errores requieren una solución a nivel empresarial. Verifica los saldos de las cuentas, los límites de transacciones o comunícate con el servicio de asistencia para conocer las restricciones específicas.

***

## Buenas prácticas para el manejo de errores

> [!TIP]
>
> **Consejo profesional**
>
> Implementa el registro estructurado desde el primer día. Incluye identificadores de correlación, códigos de error e información de contexto para facilitar la depuración cuando surjan problemas en producción.

### Implementar un registro de eventos completo

```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
function handleApiError(error, context) {
  const logEntry = {
    timestamp: new Date().toISOString(),
    context: context,
    errorCode: error.status?.code,
    errorDescription: error.status?.description,
    errorDetail: error.status?.detail,
    externalId: error.externalId,
    httpStatus: error.httpStatus
  };
  
  console.error('Localpayment API Error:', logEntry);
  // Send to your monitoring system
  sendToMonitoring(logEntry);
}
```

### Mensajes de error fáciles de entender

Crea una correspondencia entre los códigos de error técnicos y los mensajes fáciles de usar:

```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
const errorMessages = {
  '300': 'Please check your information and try again.',
  '701': 'Your payment was declined. Please use a different payment method.',
  '702': 'Payment authorization expired. Please try again.',
  '703': 'Temporary system issue. Please try again in a few minutes.',
  'default': 'An unexpected error occurred. Please contact support.'
};

function getUserMessage(errorCode) {
  return errorMessages[errorCode] || errorMessages['default'];
}
```

### Mecanismo de reintento con retroceso exponencial

```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
async function makeRequestWithRetry(apiCall, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await apiCall();
    } catch (error) {
      // Only retry on certain errors
      if (!isRetryableError(error)) {
        throw error;
      }
      
      if (attempt === maxRetries) {
        throw error;
      }
      
      // Exponential backoff
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

function isRetryableError(error) {
  const retryableCodes = ['500', '502', '503', '504', '800'];
  return retryableCodes.includes(error.status?.code);
}
```

### Patrón de disyuntor

Implementa un interruptor automático para evitar fallas en cascada:

```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
class CircuitBreaker {
  constructor(failureThreshold = 5, resetTimeout = 60000) {
    this.failureThreshold = failureThreshold;
    this.resetTimeout = resetTimeout;
    this.failureCount = 0;
    this.lastFailureTime = null;
    this.state = 'CLOSED';
  }
  
  async call(apiFunction) {
    if (this.state === 'OPEN') {
      if (Date.now() - this.lastFailureTime > this.resetTimeout) {
        this.state = 'HALF_OPEN';
      } else {
        throw new Error('Circuit breaker is OPEN');
      }
    }
    
    try {
      const result = await apiFunction();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }
  
  onSuccess() {
    this.failureCount = 0;
    this.state = 'CLOSED';
  }
  
  onFailure() {
    this.failureCount++;
    this.lastFailureTime = Date.now();
    
    if (this.failureCount >= this.failureThreshold) {
      this.state = 'OPEN';
    }
  }
}
```

***

## Próximos pasos

> [card] [Referencia de la API](https://docs.localpayment.com/es/reference/api-basics.md)
>
> Lista completa de códigos de error con explicaciones detalladas.

> [card] [Guía de pruebas](https://docs.localpayment.com/es/docs/testing.md)
>
> Aprende a probar escenarios de error en un entorno aislado (sandbox).

> [card] [Contacto de soporte](mailto:support@localpayment.com)
>
> Obtén ayuda con escenarios de error específicos.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.