Gestion des erreurs

L’API Qwoty utilise les codes de statut HTTP standard. 2xx signifie que la requête a réussi, 4xx que la requête doit être corrigée avant d’être renvoyée, et 5xx qu’un problème est survenu de notre côté.

Corps d’erreur

Chaque réponse d’erreur est un objet JSON contenant une chaîne error. Les erreurs de validation ajoutent un tableau details qui liste chaque problème :

{
  "error": "Validation error",
  "details": ["Field 'api_name' is required"]
}

Clé	Type	Description
`error`	string	Description courte de l’erreur. Toujours présente.
`details`	string[]	Présente uniquement pour les erreurs de validation : un message par champ invalide.
`success`	boolean	Certains endpoints renvoient aussi `"success": false`. Ne vous y fiez pas : utilisez le statut HTTP.

Il n’existe pas de clé message. Les messages sont destinés aux développeurs et peuvent changer : basez votre logique sur le statut HTTP, pas sur le texte exact.

Codes de statut

400 Bad Request

La requête est mal formée ou un champ est invalide. Corrigez la requête avant de la renvoyer.

Invalid JSON

{
  "error": "Invalid JSON body"
}

Unknown or read-only field

{
  "error": "Validation error",
  "details": ["Field 'description' is read-only or unknown"]
}

Empty update

{
  "error": "No fields to update"
}

Les clés inconnues sont rejetées, pas ignorées : envoyer un champ que l’endpoint n’accepte pas (par exemple un champ réservé à la création comme api_name dans un PATCH) renvoie 400.

401 Unauthorized

Le token est absent ou invalide.

Missing token

{
  "error": "Missing authorization token"
}

Invalid token

{
  "error": "Invalid or expired token"
}

Invalid or expired token est renvoyé pour un token inconnu, un token supprimé (révoqué) ou un token dont le rôle a été supprimé. Les tokens n’expirent pas d’eux-mêmes. Consultez Authentification.

403 Forbidden

Le token est valide, mais son rôle n’a pas le droit requis par l’endpoint.

{
  "error": "Insufficient permissions. Requires customer:write"
}

Consultez Permissions.

404 Not Found

L’objet n’existe pas, a été supprimé ou appartient à un autre workspace.

{
  "error": "Customer not found"
}

Certains endpoints renvoient aussi 404 lorsqu’un ID référencé n’existe pas, par exemple une entrée catalog_ids inconnue lors de la création d’un produit :

{
  "error": "Validation error",
  "details": ["Catalog(s) not found: 660e8400-e29b-41d4-a716-446655440001"]
}

409 Conflict

La requête entre en conflit avec des données existantes.

Duplicate api_name

{
  "error": "Validation error",
  "details": ["A product with api_name 'premium_widget' already exists"]
}

Category in use

{
  "error": "CATEGORY_REFERENCED_IN_DISCOUNT"
}

429 Too Many Requests

Vous avez envoyé trop de requêtes en peu de temps. Patientez puis réessayez avec un backoff exponentiel. Consultez Limites de débit et nouvelles tentatives.

500 Internal Server Error

Une erreur inattendue s’est produite.

{
  "error": "Internal server error"
}

Certains endpoints renvoient un message plus précis, par exemple Failed to create payment term. Vous pouvez réessayer les erreurs 500 avec un backoff ; si l’erreur persiste, contactez le support.

Quand réessayer

Statut	Réessayer ?
`400`, `401`, `403`, `404`, `409`	Non. Corrigez d’abord la requête, le token ou le rôle.
`429`	Oui, après un délai, avec un backoff exponentiel.
`500` et autres `5xx`	Oui, quelques fois, avec un backoff exponentiel.

Obtenir de l’aide

Si une erreur persiste, contactez support@qwoty.io en indiquant l’endpoint, le statut HTTP, le corps de la réponse et l’heure de la requête. N’incluez jamais votre token d’API.

Démarrage

Concepts essentiels

Ressources

Conformité

Politiques

Gestion des erreurs

Corps d’erreur

Codes de statut

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

429 Too Many Requests

500 Internal Server Error

Quand réessayer

Obtenir de l’aide

​Corps d’erreur

​Codes de statut

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​409 Conflict

​429 Too Many Requests

​500 Internal Server Error

​Quand réessayer

​Obtenir de l’aide

Corps d’erreur

Codes de statut

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

429 Too Many Requests

500 Internal Server Error

Quand réessayer

Obtenir de l’aide