# Errores

El formato de errores problem+json, qué significa cada código de estado y cómo tratar en código una solicitud fallida.

Cuando una solicitud falla, PDF Blocks devuelve un código de estado HTTP
estándar y un cuerpo legible por máquina que describe qué ha ido mal. Los
errores siguen el formato problem details de [RFC
7807](https://www.rfc-editor.org/rfc/rfc7807), así que puede analizar todos
los fallos igual, sea cual sea la acción que los produjo.

## El modelo problem+json

Las respuestas de error llevan `Content-Type: application/problem+json` y
esta forma:

| Atributo  | Tipo    | Descripción                                                 |
| --------- | ------- | ----------------------------------------------------------- |
| `type`    | string  | Una URL con documentación sobre el problema.                |
| `title`   | string  | Un resumen del problema legible por personas.               |
| `status`  | integer | El código de estado HTTP, repetido en el cuerpo.            |
| `errors`  | object  | Nombres de campo asociados a matrices de mensajes de error. |

La URL de `type` siempre termina en el código de estado, por ejemplo
`https://www.pdfblocks.com/docs/api/v1/error/400`, de modo que puede
ramificar según ella o según `status`. El objeto `errors` aparece cuando el
fallo está ligado a campos concretos de la solicitud (validación); en fallos
a nivel de solicitud, como una clave de API incorrecta, puede omitirse.

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/400",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "file": [
      "Could not parse the PDF document. The file may be invalid or corrupt."
    ]
  }
}
```

## Códigos de estado

| Estado | Significado                          | Qué hacer                                       |
| ------ | ------------------------------------ | ----------------------------------------------- |
| `400`  | Error de validación                  | Corrija los campos indicados y vuelva a enviar. |
| `401`  | No autorizado                        | Envíe un `X-API-Key` válido.                    |
| `404`  | No encontrado                        | Compruebe la ruta de la acción y el host.       |
| `406`  | `Accept` no aceptable                | Solicite un formato admitido.                   |
| `402`  | Pago requerido *(reservado)*         | Resuelva la facturación o la cuota.             |
| `403`  | Prohibido *(reservado)*              | La clave no tiene permiso para esta llamada.    |
| `413`  | Carga demasiado grande *(reservado)* | Envíe un archivo más pequeño.                   |
| `429`  | Demasiadas solicitudes *(reservado)* | Espere y vuelva a intentarlo.                   |
| `5xx`  | Error del servidor (poco frecuente)  | Reintente con espera exponencial.               |

### 400: error de validación

Un parámetro no es válido, o `file` no es un PDF legible. El objeto `errors`
indica cada campo problemático.

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/400",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "line_1": ["The field line_1 must be a string with a maximum length of 32."]
  }
}
```

Lea `errors` campo por campo, corrija la entrada y vuelva a enviarla. Un
`400` no tendrá éxito al reintentarlo sin cambios.

### 401: no autorizado

La cabecera `X-API-Key` falta, está mal formada o no es una clave válida.

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/401",
  "title": "The request is missing a valid API key.",
  "status": 401
}
```

Establezca en la cabecera `X-API-Key` una clave válida de su
[dashboard](https://dashboard.pdfblocks.com) y envíe la solicitud por HTTPS.
Consulte [Autenticación](/docs/api/authentication).

### 404: no encontrado

La ruta no resuelve a ninguna acción, normalmente por un error tipográfico en
el nombre de la acción o por falta del segmento de versión.

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/404",
  "title": "The requested resource was not found.",
  "status": 404
}
```

Verifique la ruta (por ejemplo `/v1/add_text_watermark`) y que está llamando
a una [URL base](/docs/api/regions-and-data-residency) válida.

### 406: `Accept` no aceptable

Una acción de varios documentos ha recibido una cabecera `Accept` que no
puede satisfacer.

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/406",
  "title": "The requested Accept header cannot be satisfied.",
  "status": 406
}
```

Solicite uno de los formatos admitidos, `application/zip`, `application/json`
o `multipart/mixed`, u omita `Accept` para obtener el ZIP predeterminado.
Consulte [Formatos de respuesta](/docs/api/response-formats).

### Códigos de estado reservados

<Note>
  **Con vistas al futuro.** Las respuestas `402`, `403`, `413` y `429` forman
  parte del contrato de la API pero **todavía no se aplican**. Trátelas desde
  ya para que su cliente esté listo cuando entren en vigor. Los detalles de
  uso y de rate limits están en [Rate limits y
  uso](/docs/api/rate-limits-and-usage).
</Note>

**`402`: pago requerido.** Una condición de facturación o de cuota de su
plan.

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/402",
  "title": "Payment is required to complete this request.",
  "status": 402
}
```

**`403`: prohibido.** La clave es válida pero no tiene permiso para usar este
recurso.

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/403",
  "title": "You do not have permission to access this resource.",
  "status": 403
}
```

**`413`: carga demasiado grande.** El cuerpo de la solicitud supera el tamaño
admitido.

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/413",
  "title": "The request payload is too large.",
  "status": 413
}
```

**`429`: demasiadas solicitudes.** Ha superado el rate limit de su plan.

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/429",
  "title": "Too many requests. Please retry later.",
  "status": 429
}
```

### 5xx: errores del servidor

Un estado `5xx` indica un problema de nuestro lado y es poco frecuente. Es
transitorio: reintente la misma solicitud con [espera
exponencial](/docs/api/rate-limits-and-usage).

## Cómo tratar los errores en el código

Analice el cuerpo una vez y ramifique según `status` (o según el estado final
de `type`):

- **`400`**: lea el objeto `errors`, asocie cada mensaje a su campo y corrija
  la entrada. No reintente a ciegas; la misma solicitud volverá a fallar.
- **`401`, `403`, `404`, `406`**: la solicitud en sí es incorrecta. Corrija
  la cabecera, la ruta o `Accept` y vuelva a enviarla; reintentarla sin
  cambios no servirá.
- **`402`, `413`**: una condición de cuenta o de tamaño. Resuelva la
  facturación o envíe un archivo más pequeño; tal cual no tendrán éxito al
  reintentar.
- **`429` y `5xx`**: transitorios. Reintente con espera exponencial, respete
  la cabecera `Retry-After` cuando esté presente y limite el número de
  intentos. Consulte [Rate limits y uso](/docs/api/rate-limits-and-usage).

Lea siempre el objeto `errors` cuando esté presente: indica exactamente qué
hay que corregir.