Référence des erreurs

Toutes les erreurs de l’API qr3.app suivent la spécification RFC 7807 Problem Details avec le header Content-Type: application/problem+json.

{
  "type": "https://docs.qr3.app/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "QR code qr_xxx not found"
}

`errors/validation`

HTTP 422 Unprocessable Entity

Les données d’entrée ont échoué à la validation du schéma. La réponse contient un tableau errors avec des détails précis par champ.

{
  "type": "https://docs.qr3.app/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "Request body validation failed",
  "errors": [
    { "field": "url", "message": "Invalid URL format" }
  ]
}

Causes : Champs obligatoires manquants, types de données incorrects, valeurs hors limites, format d’URL invalide.

`errors/bad-request`

HTTP 400 Bad Request

Le corps n’est pas un JSON valide bien que Content-Type: application/json soit défini (par exemple, une virgule traînante, un corps tronqué ou vide).

`errors/authentication`

HTTP 401 Unauthorized

La clé API est manquante, mal formatée, expirée ou révoquée.

Correction : Vérifiez que l’en-tête Authorization: Bearer qr3_sk_... est présent et que la clé est active.

`errors/unauthorized`

HTTP 401 Unauthorized

Un webhook entrant (POST /v1/webhooks/clerk, POST /v1/webhooks/eu-registry) a été appelé sans signature ou secret valide. Une clé API manquante ou invalide renvoie à la place errors/authentication.

`errors/authorization`

HTTP 403 Forbidden

La clé API est valide, mais ne possède pas le scope requis ou les permissions nécessaires.

`errors/forbidden`

HTTP 403 Forbidden

La ressource existe, mais appartient à un autre Workspace ou à une autre organisation.

`errors/document-immutable`

HTTP 403 Forbidden

Un document DPP téléversé avec is_immutable ne peut pas être supprimé.

`errors/not-found`

HTTP 404 Not Found

La ressource demandée n’existe pas ou a été supprimée.

`errors/conflict`

HTTP 409 Conflict

Une ressource avec le même identifiant unique existe déjà (par exemple, un slug en double ou une collision d’Idempotency-Key).

`errors/subscription-exists`

HTTP 409 Conflict

POST /v1/billing/checkout a été appelé alors que l’organisation possède déjà un abonnement. Modifiez plutôt le forfait dans le portail de facturation.

`errors/rate-limited`

HTTP 429 Too Many Requests

La limite de requêtes par minute de la clé API a été dépassée. La réponse contient les en-têtes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset.

`errors/rate-limit`

HTTP 429 Too Many Requests

Une limite de requêtes spécifique à la ressource a été dépassée (par exemple, 200 codes QR par jour et par Workspace).

`errors/plan-limit`

HTTP 422 Unprocessable Entity

Votre forfait actuel ne permet pas cette action (par exemple, quota de DPP ou de codes dynamiques épuisé, lot trop volumineux, trop d’espaces de travail ou de membres de l’équipe). Mise à niveau requise.

`errors/invalid-file-type`

HTTP 400 Bad Request

Le fichier téléversé est d’un type que le point de terminaison n’accepte pas, ou son contenu ne correspond pas au Content-Type déclaré.

`errors/file-too-large`

HTTP 413 Payload Too Large

Le fichier téléversé dépasse la limite de taille du forfait ou du point de terminaison.

`errors/storage-limit-exceeded`

HTTP 422 Unprocessable Entity

Le téléversement dépasserait l’espace de stockage total de l’espace de travail ou du DPP.

`errors/not-configured`

HTTP 503 Service Unavailable

Un service ou une configuration requis est manquant (par exemple, Stripe non configuré, clé API Web Risk non définie).

`errors/unsafe-url`

HTTP 422 Unprocessable Entity

L’URL a été rejetée car elle a été classée comme dangereuse par Google Web Risk (malware, phishing, ingénierie sociale).

`errors/url-flagged`

HTTP 422 Unprocessable Entity

Réservé aux URL classées comme dangereuses ultérieurement lors de l’analyse périodique.

`errors/already-submitted`

HTTP 409 Conflict

Soumission en double — par exemple, un score NPS a déjà été soumis pour ce Workspace ce mois-ci.

`errors/unprocessable-entity`

HTTP 422 Unprocessable Entity

Une action d’administration n’est pas autorisée (par exemple, usurper l’identité d’un autre superadmin). Seuls les points de terminaison de superadmin renvoient ce type.

`errors/request-error`

HTTP 4xx Client Error

Type de repli pour les erreurs client sans type plus spécifique ; le statut se trouve dans la réponse. L’API n’a actuellement aucun chemin connu qui le renvoie.

`errors/internal`

HTTP 500 Internal Server Error

Une erreur inattendue est survenue sur le serveur. Veuillez réessayer la requête. Si le problème persiste : [email protected].