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

# Errores

> Formato y códigos de error que devuelve la API de GetQR.

> [!NOTE]
>
> La API de GetQR está en beta y solo está disponible para algunos espacios de trabajo. Los detalles pueden cambiar antes del lanzamiento general.

La API de GetQR usa los códigos de estado HTTP estándar. Las solicitudes correctas devuelven `2xx`. Las solicitudes fallidas devuelven `4xx` o `5xx` con un cuerpo JSON que explica qué ha fallado.

## Formato de los errores

Todos los errores tienen la misma forma: un código estable, un mensaje legible y un enlace a la descripción de ese código.

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized: Invalid API key.",
    "doc_url": "https://getqr.com/account/api-docs#error-unauthorized"
  }
}
```

**error.code** `string` *required*

Código de error estable y legible por máquinas. Úsalo en tu código en lugar del mensaje. Consulta [Códigos de error](#códigos-de-error).

**error.message** `string` *required*

Descripción legible del problema. El texto puede cambiar.

**error.doc\_url** `string` *required*

Enlace a la descripción del código de error en la documentación de la API de tu cuenta de GetQR.

## Códigos de error

| Código | Estado HTTP | Cuándo ocurre |
| - | - | - |
| `bad_request` | 400 | La solicitud está mal formada: el cuerpo no es JSON válido, a la cabecera `Authorization` le falta el prefijo `Bearer ` o la acción no está permitida en el estado actual del recurso (por ejemplo, cancelar una creación masiva ya terminada). |
| `unauthorized` | 401 | Falta la clave de API o no es válida, por ejemplo porque se ha regenerado. |
| `forbidden` | 403 | La suscripción del propietario del espacio de trabajo no está activa, o tu rol en el espacio de trabajo no permite esta acción. |
| `exceeded_limit` | 403 | Has alcanzado un límite del plan. En el plan Single QR, al crear o duplicar un código QR cuando el espacio de trabajo ya tiene uno, o al iniciar una creación masiva. |
| `not_found` | 404 | El recurso no existe o no está en tu espacio de trabajo, el endpoint no existe o la API no está habilitada para tu espacio de trabajo. |
| `method_not_allowed` | 405 | El endpoint existe, pero no acepta este método HTTP. La cabecera `Allow` indica los métodos que acepta. |
| `conflict` | 409 | La solicitud choca con datos existentes: el slug del enlace corto ya está en uso, una solicitud con la misma `Idempotency-Key` sigue en curso, una programación se solapa con otra existente o un archivo de la creación masiva aún no está listo. |
| `invite_pending` | 409 | Te han invitado al espacio de trabajo, pero aún no te has unido. Las solicitudes con clave de API no lo devuelven: el espacio de trabajo de la clave siempre es uno al que perteneces. |
| `invite_expired` | 410 | Tu invitación al espacio de trabajo ha caducado. Las solicitudes con clave de API no lo devuelven, por el mismo motivo. |
| `unprocessable_entity` | 422 | El cuerpo o los parámetros de consulta no han superado la validación. El mensaje indica el campo y qué le pasa. Consulta [Errores de validación](#errores-de-validación). |
| `rate_limit_exceeded` | 429 | La clave de API ha agotado sus solicitudes en la ventana actual. Consulta [Límites de tasa](https://docs.getqr.com/es/api/rate-limits.md). |
| `internal_server_error` | 500 | Algo ha fallado por nuestra parte. Vuelve a intentarlo más tarde y contacta con soporte si sigue ocurriendo. |

## Errores de validación

Cuando el cuerpo o los parámetros de consulta no superan la validación, la API responde `422`. El mensaje describe el primer campo no válido con el formato `<issue>: <field>: <details>`:

```json theme={null}
{
  "error": {
    "code": "unprocessable_entity",
    "message": "too_big: pageSize: Max page size is 100.",
    "doc_url": "https://getqr.com/account/api-docs#error-unprocessable_entity"
  }
}
```

Los campos anidados usan notación de puntos, por ejemplo `link.url`.

## Gestiona los errores

* Decide según `error.code`, no según `error.message`.
* No reintentes los errores `4xx` sin cambios: corrige antes la solicitud. Las excepciones son un `409` por una solicitud aún en curso y `429`.
* Ante un `429`, espera los segundos que indica la cabecera `Retry-After`. Consulta [Límites de tasa](https://docs.getqr.com/es/api/rate-limits.md#si-superas-el-límite).
* Reintenta los errores `5xx` con espera exponencial.

## Problemas habituales

> [accordion] Todas las solicitudes devuelven 404 "This endpoint is not available."
>
> La API está en beta y todavía no está habilitada para tu espacio de trabajo.

> [accordion] 404 "This endpoint does not exist."
>
> La ruta es incorrecta. Compárala con las páginas de los endpoints y comprueba que empieza por `/api/v1/`.

> [accordion] 403 "Access denied: This account does not have an active subscription."
>
> La suscripción del propietario del espacio de trabajo ha finalizado. La clave de API vuelve a funcionar en cuanto el propietario renueva la suscripción.

> [accordion] 403 "API access is not available for this role."
>
> Tu rol en el espacio de trabajo es lector. Solo el propietario del espacio de trabajo y los editores pueden usar la API.

## Siguientes pasos

> [card] [Límites de tasa](https://docs.getqr.com/es/api/rate-limits.md)

> [card] [Autenticación](https://docs.getqr.com/es/api/authentication.md)


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