Erreurs

Vue d'ensemble

Lorsqu'un problème survient avec une requête API, Oquira retourne une réponse d'erreur structurée qui vous aide à identifier et résoudre le problème.

Codes de Statut HTTP

Oquira utilise les codes de réponse HTTP standards pour indiquer le succès ou l'échec d'une requête API.

Codes de Succès

Code	Description
`200 OK`	La requête a réussi
`201 Created`	Une ressource a été créée avec succès
`204 No Content`	La requête a réussi sans corps de réponse

Codes d'Erreur Client

Code	Description
`400 Bad Request`	La requête est invalide (ex: JSON malformé, champs manquants)
`401 Unauthorized`	L'authentification est requise ou a échoué
`403 Forbidden`	Vous n'avez pas la permission d'effectuer cette action
`404 Not Found`	La ressource demandée n'existe pas
`409 Conflict`	Conflit avec l'état actuel (ex: identifiant dupliqué)
`422 Unprocessable Entity`	Les données n'ont pas passé la validation
`429 Too Many Requests`	Limite de taux dépassée

Codes d'Erreur Serveur

Code	Description
`500 Internal Server Error`	Une erreur inattendue s'est produite côté serveur
`502 Bad Gateway`	Problème temporaire du service en amont
`503 Service Unavailable`	Service temporairement indisponible

Format de Réponse d'Erreur

Toutes les réponses d'erreur suivent cette structure :

{
  "success": false,
  "error": {
    "code": "CODE_ERREUR",
    "message": "Explication lisible de ce qui s'est mal passé",
    "details": {
      "field": "Quel champ a causé l'erreur",
      "reason": "Pourquoi cela a échoué"
    },
    "timestamp": "2024-03-20T10:00:00.000Z",
    "requestId": "req_5f2b8c9d1e"
  }
}

Référence des Codes d'Erreur

Erreurs d'Authentification

Code d'Erreur	Statut HTTP	Description
`AUTHENTICATION_ERROR`	`401`	Identifiants manquants ou invalides
`TOKEN_EXPIRED`	`401`	Le token de session a expiré
`INVALID_API_KEY`	`401`	La clé API est invalide ou malformée
`KEY_REVOKED`	`403`	La clé API a été révoquée

Erreurs d'Autorisation

Code d'Erreur	Statut HTTP	Description
`AUTHORIZATION_ERROR`	`403`	Permissions insuffisantes pour cette opération
`SCOPE_REQUIRED`	`403`	La clé API n'a pas la portée requise
`RESOURCE_FORBIDDEN`	`403`	L'accès à cette ressource spécifique est refusé

Erreurs de Validation

Code d'Erreur	Statut HTTP	Description
`VALIDATION_ERROR`	`422`	Échec de validation (voir `details` pour les champs)
`INVALID_FORMAT`	`400`	Corps de requête malformé (ex: JSON invalide)
`MISSING_FIELD`	`400`	Un champ obligatoire est manquant
`INVALID_VALUE`	`422`	Une valeur de champ est hors de la plage acceptable

Erreurs de Ressource

Code d'Erreur	Statut HTTP	Description
`NOT_FOUND`	`404`	La ressource demandée n'a pas été trouvée
`DUPLICATE_RESOURCE`	`409`	Une ressource avec cet identifiant existe déjà
`RESOURCE_CONFLICT`	`409`	L'état de la ressource est en conflit avec l'opération

Erreurs de Limite de Taux

Code d'Erreur	Statut HTTP	Description
`API_RATE_LIMIT_EXCEEDED`	`429`	Trop de requêtes API en peu de temps
`QUOTA_EXCEEDED`	`403`	Le quota mensuel ou journalier a été dépassé

Erreurs de File et Ticket

Code d'Erreur	Statut HTTP	Description
`QUEUE_CLOSED`	`403`	La file d'attente est actuellement fermée
`QUEUE_PAUSED`	`403`	La file d'attente est temporairement suspendue
`QUEUE_FULL`	`403`	La capacité maximale de la file a été atteinte
`TICKET_LIMIT_REACHED`	`403`	Le client a atteint le maximum de tickets actifs
`TICKET_EXPIRED`	`410`	Le ticket a expiré
`TICKET_ALREADY_CALLED`	`409`	Ce ticket a déjà été appelé
`NO_TICKETS_WAITING`	`404`	Aucun ticket n'attend dans cette file

Erreurs d'Abonnement

Code d'Erreur	Statut HTTP	Description
`SUBSCRIPTION_REQUIRED`	`403`	Cette fonctionnalité nécessite un abonnement payant
`PLAN_LIMIT_EXCEEDED`	`403`	Vous avez dépassé les limites de votre forfait

Détails des Erreurs de Validation

Pour VALIDATION_ERROR, l'objet details fournit des informations spécifiques sur ce qui a échoué :

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "La validation a échoué pour 2 champs",
    "details": {
      "errors": [
        {
          "field": "email",
          "message": "Doit être une adresse email valide",
          "received": "email-invalide"
        },
        {
          "field": "phone",
          "message": "Doit correspondre au format : +1234567890",
          "received": "123"
        }
      ]
    },
    "timestamp": "2024-03-20T10:00:00.000Z",
    "requestId": "req_5f2b8c9d1e"
  }
}

Guide de Dépannage

1. Vérifiez le Message d'Erreur

Le champ message fournit une explication lisible. Commencez ici pour comprendre ce qui s'est mal passé.

2. Inspectez les Détails

Pour les erreurs de validation, l'objet details vous indique exactement quels champs ont échoué et pourquoi.

3. Revoyez Votre Requête

Points courants à vérifier :

Le JSON est-il correctement formaté ?
Tous les champs obligatoires sont-ils présents ?
Les valeurs des champs sont-elles du bon type ?
Votre clé API est-elle incluse dans les en-têtes ?

4. Vérifiez les Limites de Taux

Si vous recevez une erreur 429 :

Vérifiez l'en-tête Retry-After pour savoir quand réessayer
Passez en revue vos patterns d'utilisation dans le tableau de bord
Envisagez d'implémenter une file d'attente de requêtes

5. Notez le Request ID

Loggez toujours le requestId des réponses d'erreur. Lorsque vous contactez le support, fournissez :

Le requestId
L'URL de l'endpoint que vous avez appelé
L'heure approximative de l'erreur
Une description de ce que vous essayiez de faire

Contacter le Support

Si vous ne pouvez pas résoudre un problème :

Loggez le requestId et les détails de l'erreur
Consultez notre page de statut pour tout incident en cours
Envoyez un email à support@oquira.com avec :
- Votre requestId
- L'endpoint et la méthode que vous avez essayés
- Le corps de votre requête (avec les données sensibles masquées)
- Les étapes pour reproduire le problème

Étapes Suivantes

Limites de taux - Comprendre les limites d'utilisation de l'API
Réponses - Découvrir les formats de réponse
Authentification - Revoir les méthodes d'authentification

Vue d'ensemble

Lorsqu'un problème survient avec une requête API, Oquira retourne une réponse d'erreur structurée qui vous aide à identifier et résoudre le problème.

Codes de Statut HTTP

Oquira utilise les codes de réponse HTTP standards pour indiquer le succès ou l'échec d'une requête API.

Codes de Succès

Code	Description
`200 OK`	La requête a réussi
`201 Created`	Une ressource a été créée avec succès
`204 No Content`	La requête a réussi sans corps de réponse

Codes d'Erreur Client

Code	Description
`400 Bad Request`	La requête est invalide (ex: JSON malformé, champs manquants)
`401 Unauthorized`	L'authentification est requise ou a échoué
`403 Forbidden`	Vous n'avez pas la permission d'effectuer cette action
`404 Not Found`	La ressource demandée n'existe pas
`409 Conflict`	Conflit avec l'état actuel (ex: identifiant dupliqué)
`422 Unprocessable Entity`	Les données n'ont pas passé la validation
`429 Too Many Requests`	Limite de taux dépassée

Codes d'Erreur Serveur

Code	Description
`500 Internal Server Error`	Une erreur inattendue s'est produite côté serveur
`502 Bad Gateway`	Problème temporaire du service en amont
`503 Service Unavailable`	Service temporairement indisponible

Format de Réponse d'Erreur

Toutes les réponses d'erreur suivent cette structure :

{
  "success": false,
  "error": {
    "code": "CODE_ERREUR",
    "message": "Explication lisible de ce qui s'est mal passé",
    "details": {
      "field": "Quel champ a causé l'erreur",
      "reason": "Pourquoi cela a échoué"
    },
    "timestamp": "2024-03-20T10:00:00.000Z",
    "requestId": "req_5f2b8c9d1e"
  }
}

Référence des Codes d'Erreur

Erreurs d'Authentification

Code d'Erreur	Statut HTTP	Description
`AUTHENTICATION_ERROR`	`401`	Identifiants manquants ou invalides
`TOKEN_EXPIRED`	`401`	Le token de session a expiré
`INVALID_API_KEY`	`401`	La clé API est invalide ou malformée
`KEY_REVOKED`	`403`	La clé API a été révoquée

Erreurs d'Autorisation

Code d'Erreur	Statut HTTP	Description
`AUTHORIZATION_ERROR`	`403`	Permissions insuffisantes pour cette opération
`SCOPE_REQUIRED`	`403`	La clé API n'a pas la portée requise
`RESOURCE_FORBIDDEN`	`403`	L'accès à cette ressource spécifique est refusé

Erreurs de Validation

Code d'Erreur	Statut HTTP	Description
`VALIDATION_ERROR`	`422`	Échec de validation (voir `details` pour les champs)
`INVALID_FORMAT`	`400`	Corps de requête malformé (ex: JSON invalide)
`MISSING_FIELD`	`400`	Un champ obligatoire est manquant
`INVALID_VALUE`	`422`	Une valeur de champ est hors de la plage acceptable

Erreurs de Ressource

Code d'Erreur	Statut HTTP	Description
`NOT_FOUND`	`404`	La ressource demandée n'a pas été trouvée
`DUPLICATE_RESOURCE`	`409`	Une ressource avec cet identifiant existe déjà
`RESOURCE_CONFLICT`	`409`	L'état de la ressource est en conflit avec l'opération

Erreurs de Limite de Taux

Code d'Erreur	Statut HTTP	Description
`API_RATE_LIMIT_EXCEEDED`	`429`	Trop de requêtes API en peu de temps
`QUOTA_EXCEEDED`	`403`	Le quota mensuel ou journalier a été dépassé

Erreurs de File et Ticket

Code d'Erreur	Statut HTTP	Description
`QUEUE_CLOSED`	`403`	La file d'attente est actuellement fermée
`QUEUE_PAUSED`	`403`	La file d'attente est temporairement suspendue
`QUEUE_FULL`	`403`	La capacité maximale de la file a été atteinte
`TICKET_LIMIT_REACHED`	`403`	Le client a atteint le maximum de tickets actifs
`TICKET_EXPIRED`	`410`	Le ticket a expiré
`TICKET_ALREADY_CALLED`	`409`	Ce ticket a déjà été appelé
`NO_TICKETS_WAITING`	`404`	Aucun ticket n'attend dans cette file

Erreurs d'Abonnement

Code d'Erreur	Statut HTTP	Description
`SUBSCRIPTION_REQUIRED`	`403`	Cette fonctionnalité nécessite un abonnement payant
`PLAN_LIMIT_EXCEEDED`	`403`	Vous avez dépassé les limites de votre forfait

Détails des Erreurs de Validation

Pour VALIDATION_ERROR, l'objet details fournit des informations spécifiques sur ce qui a échoué :

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "La validation a échoué pour 2 champs",
    "details": {
      "errors": [
        {
          "field": "email",
          "message": "Doit être une adresse email valide",
          "received": "email-invalide"
        },
        {
          "field": "phone",
          "message": "Doit correspondre au format : +1234567890",
          "received": "123"
        }
      ]
    },
    "timestamp": "2024-03-20T10:00:00.000Z",
    "requestId": "req_5f2b8c9d1e"
  }
}

Le JSON est-il correctement formaté ?
Tous les champs obligatoires sont-ils présents ?
Les valeurs des champs sont-elles du bon type ?
Votre clé API est-elle incluse dans les en-têtes ?

4. Vérifiez les Limites de Taux

Si vous recevez une erreur 429 :

Vérifiez l'en-tête Retry-After pour savoir quand réessayer
Passez en revue vos patterns d'utilisation dans le tableau de bord
Envisagez d'implémenter une file d'attente de requêtes

5. Notez le Request ID

Loggez toujours le requestId des réponses d'erreur. Lorsque vous contactez le support, fournissez :

Le requestId
L'URL de l'endpoint que vous avez appelé
L'heure approximative de l'erreur
Une description de ce que vous essayiez de faire

Contacter le Support

Si vous ne pouvez pas résoudre un problème :

Loggez le requestId et les détails de l'erreur
Consultez notre page de statut pour tout incident en cours
Envoyez un email à support@oquira.com avec :
- Votre requestId
- L'endpoint et la méthode que vous avez essayés
- Le corps de votre requête (avec les données sensibles masquées)
- Les étapes pour reproduire le problème

Étapes Suivantes

Limites de taux - Comprendre les limites d'utilisation de l'API
Réponses - Découvrir les formats de réponse
Authentification - Revoir les méthodes d'authentification

Erreurs

On this page

Erreurs

On this page