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

# Errores

> Como interpretar respuestas de error en SimplePay, que hacer con 400, 401, 403, 404, 409, 422 y 5xx, y como instrumentar retries seguros.

La API de SimplePay usa codigos HTTP para separar errores de validacion, autenticacion, permisos, estado de negocio y fallas temporales.

## Codigos comunes

| Codigo | Significado                                               | Que hacer                               |
| ------ | --------------------------------------------------------- | --------------------------------------- |
| `400`  | Request invalido o JSON mal formado.                      | Corrige el body antes de reintentar.    |
| `401`  | Falta API key o no es valida.                             | Revisa `Authorization: Bearer ...`.     |
| `403`  | Scope, tenant policy o live gate denegado.                | Revisa scopes, ambiente y policy.       |
| `404`  | Objeto no existe o no pertenece al tenant.                | Verifica ID y ambiente.                 |
| `409`  | Conflicto de estado o idempotencia.                       | Lee el objeto existente y decide.       |
| `422`  | Request valido sintacticamente, invalido para el dominio. | Corrige campos de negocio.              |
| `429`  | Rate limit o velocity gate.                               | Backoff y revisa limites.               |
| `5xx`  | Falla temporal de plataforma.                             | Reintenta con la misma idempotency key. |

## Estrategia de retries

<Steps>
  <Step title="Reintenta solo operaciones seguras">
    Para writes, reintenta si y solo si mandaste `Idempotency-Key`.
  </Step>

  <Step title="Usa exponential backoff">
    No hagas loops agresivos contra `429` o `5xx`.
  </Step>

  <Step title="Guarda request IDs">
    Si la respuesta incluye identificadores de debugging, guardalos junto a tu
    orden.
  </Step>

  <Step title="No confirmes por timeout">
    Si tu create checkout tuvo timeout, lee por tu referencia o espera webhook.
    No marques pagado por asumir exito.
  </Step>
</Steps>

## Ejemplo de handler

```ts api-client.ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
export async function simplePayRequest(path: string, init: RequestInit) {
  const response = await fetch(`https://api.simplepay.mx${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.SIMPLEPAY_API_KEY}`,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });

  const text = await response.text();
  const payload = text ? JSON.parse(text) : null;

  if (!response.ok) {
    const retryable = response.status === 429 || response.status >= 500;
    throw Object.assign(new Error(payload?.message ?? "SimplePay API error"), {
      status: response.status,
      retryable,
      payload,
    });
  }

  return payload;
}
```

## Errores de politica

Un `403` no siempre significa "API key mala". Tambien puede significar:

* El tenant no tiene habilitado el producto.
* El monto excede limites.
* El metodo de pago no esta permitido.
* Live esta bloqueado.
* El flujo necesita revision manual.
* La key no tiene el scope requerido.

Usa [Payment policy](/api-reference/overview#policy-preflight) para inspeccionar elegibilidad antes de mostrar un metodo de pago o una opcion de installments.