> ## 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.

# Erreurs

> Format et codes des erreurs renvoyées par l'API GetQR.

> [!NOTE]
>
> L'API GetQR est en version bêta et réservée à certains espaces de travail. Certains détails peuvent changer avant la disponibilité générale.

L'API GetQR utilise les codes de statut HTTP standard. Les requêtes réussies renvoient `2xx`. Les requêtes en échec renvoient `4xx` ou `5xx` avec un corps JSON qui explique le problème.

## Format des erreurs

Toutes les erreurs ont la même forme : un code stable, un message lisible et un lien vers la description de ce code.

```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*

Code d'erreur stable et lisible par une machine. Utilisez-le dans votre code plutôt que le message. Consultez [Codes d'erreur](#codes-d-erreur).

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

Description lisible du problème. Sa formulation peut changer.

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

Lien vers la description du code d'erreur dans la documentation API de votre compte GetQR.

## Codes d'erreur

| Code | Statut HTTP | Quand il se produit |
| - | - | - |
| `bad_request` | 400 | La requête est mal formée : le corps n'est pas un JSON valide, l'en-tête `Authorization` n'a pas le préfixe `Bearer `, ou l'action n'est pas permise dans l'état actuel de la ressource (par exemple, annuler une création en masse terminée). |
| `unauthorized` | 401 | La clé API est absente ou invalide, par exemple parce qu'elle a été régénérée. |
| `forbidden` | 403 | L'abonnement du propriétaire de l'espace de travail n'est pas actif, ou votre rôle dans l'espace de travail ne permet pas cette action. |
| `exceeded_limit` | 403 | Vous avez atteint une limite de votre offre. Avec l'offre Single QR : créer ou dupliquer un QR code alors que l'espace de travail en a déjà un, ou lancer une création en masse. |
| `not_found` | 404 | La ressource n'existe pas ou n'est pas dans votre espace de travail, l'endpoint n'existe pas, ou l'API n'est pas activée pour votre espace de travail. |
| `method_not_allowed` | 405 | L'endpoint existe mais n'accepte pas cette méthode HTTP. L'en-tête `Allow` liste les méthodes acceptées. |
| `conflict` | 409 | La requête entre en conflit avec des données existantes : le slug du lien court est déjà pris, une requête avec la même `Idempotency-Key` est encore en cours, une programmation chevauche une programmation existante, ou une archive de création en masse n'est pas encore prête. |
| `invite_pending` | 409 | Vous avez été invité dans l'espace de travail mais ne l'avez pas encore rejoint. Les requêtes avec une clé API ne le renvoient pas : l'espace de travail de la clé est toujours un espace dont vous êtes membre. |
| `invite_expired` | 410 | Votre invitation à l'espace de travail a expiré. Les requêtes avec une clé API ne le renvoient pas, pour la même raison. |
| `unprocessable_entity` | 422 | Le corps ou les paramètres de requête n'ont pas passé la validation. Le message indique le champ et le problème. Consultez [Erreurs de validation](#erreurs-de-validation). |
| `rate_limit_exceeded` | 429 | La clé API a épuisé ses requêtes pour la fenêtre en cours. Consultez [Limites de débit](https://docs.getqr.com/fr/api/rate-limits.md). |
| `internal_server_error` | 500 | Un problème est survenu de notre côté. Réessayez plus tard et contactez le support si le problème persiste. |

## Erreurs de validation

Quand le corps ou les paramètres de requête ne passent pas la validation, l'API répond `422`. Le message décrit le premier champ invalide sous la forme `<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"
  }
}
```

Les champs imbriqués utilisent la notation pointée, par exemple `link.url`.

## Gérer les erreurs

* Basez votre logique sur `error.code`, pas sur `error.message`.
* Ne relancez pas les erreurs `4xx` à l'identique : corrigez d'abord la requête. Exceptions : un `409` pour une requête encore en cours, et `429`.
* En cas de `429`, attendez le nombre de secondes indiqué dans l'en-tête `Retry-After`. Consultez [Limites de débit](https://docs.getqr.com/fr/api/rate-limits.md#en-cas-de-dépassement-de-la-limite).
* Relancez les erreurs `5xx` avec un backoff exponentiel.

## Problèmes courants

> [accordion] Chaque requête renvoie 404 « This endpoint is not available. »
>
> L'API est en version bêta et n'est pas encore activée pour votre espace de travail.

> [accordion] 404 "This endpoint does not exist."
>
> Le chemin est incorrect. Comparez-le aux pages des endpoints et vérifiez qu'il commence par `/api/v1/`.

> [accordion] 403 "Access denied: This account does not have an active subscription."
>
> L'abonnement du propriétaire de l'espace de travail a pris fin. La clé API fonctionne à nouveau dès que le propriétaire se réabonne.

> [accordion] 403 "API access is not available for this role."
>
> Votre rôle dans l'espace de travail est Viewer. Seuls le propriétaire de l'espace de travail et les Editors peuvent utiliser l'API.

## Et ensuite

> [card] [Limites de débit](https://docs.getqr.com/fr/api/rate-limits.md)

> [card] [Authentification](https://docs.getqr.com/fr/api/authentication.md)


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