Statuts & codes

Référence complète des valeurs énumérées de l'API : statuts de livraison, types de véhicule, codes d'erreur et limites de débit.

Statuts de livraison

Le champ status d'une livraison prend l'une des valeurs suivantes. Les statuts marqués terminaux sont définitifs.

Code	Libellé	Description
`PENDING_PAYMENT`	En attente de paiement	Créée, en attente du blocage du montant (carte refusée : page de paiement à ouvrir).
`SEARCHING_DRIVER`	Recherche d'un coursier	Montant bloqué ; un coursier est en cours de recherche.
`EN_ROUTE_PICKUP`	En route vers l'enlèvement	Un coursier a accepté la course et se dirige vers le point d'enlèvement.
`AT_PICKUP`	Sur le lieu d'enlèvement	Le coursier est arrivé sur le lieu d'enlèvement.
`PICKED_UP`	Colis récupéré	Le colis a été récupéré.
`EN_ROUTE_DROPOFF`	En route vers la livraison	Le coursier se dirige vers le point de livraison.
`AT_DROPOFF`	Coursier à destination	Le coursier est arrivé au point de livraison.
`INCIDENT`	Incident en cours	Livraison suspendue après un incident, reprise par l'équipe CONVOY.
`DELIVERED`terminal	Livré	Le colis a été remis ; preuve de livraison validée ; montant débité.
`CANCELED`terminal	Annulé	La livraison a été annulée ; le montant bloqué est libéré.
`EXPIRED`terminal	Expirée (aucun coursier)	Paiement non effectué dans les 30 minutes, ou aucun coursier disponible ; rien n'est débité.

Types de véhicule

Valeurs acceptées par le champ vehicle lors de la création d'une livraison.

Code	Véhicule	Capacité	Usage typique
`bike`	Vélo	≤ 5 kg	Plis, petits colis, intra-muros.
`moto`	Moto	≤ 15 kg	Express urbain, documents urgents.
`car`	Car	≤ 50 kg	Colis volumineux, plusieurs articles.
`van`	Van	≤ 300 kg	Mobilier, lots, électroménager.
`xl`	XL	Palettes	Charges lourdes, transport palettisé.

Codes d'erreur

CONVOY utilise les codes de statut HTTP conventionnels. Les réponses d'erreur incluent un objet error avec un type, un code machine et un message lisible.

Structure d'erreur

{
  "error": {
    "type": "validation_error",
    "code": "address_not_found",
    "message": "Adresse introuvable : vérifiez la rue, le code postal et la ville.",
    "param": "dropoff"
  }
}

param désigne, quand c'est utile, le champ en cause. Principaux codes : invalid_api_key, missing_param, invalid_vehicle, field_too_long, invalid_metadata, address_not_found, service_unavailable, unsupported_proof, payment_method_required, email_unverified, too_late, rate_limited.

Statut	Type	Signification
400	`invalid_request_error`	Requête mal formée (JSON invalide, champ manquant).
401	`authentication_error`	Clé API absente, invalide ou révoquée.
403	`permission_error`	Clé valide mais non autorisée pour cette ressource.
404	`not_found_error`	La ressource demandée est introuvable.
409	`conflict_error`	Conflit d'état (ex. annulation après l'enlèvement : too_late).
422	`validation_error`	Paramètres valides mais refusés (adresse introuvable, service non proposé, aucune carte enregistrée).
429	`rate_limit_error`	Trop de requêtes : limite de débit atteinte.
5xx	`api_error`	Erreur interne ou paiement indisponible. Réessayez avec un délai exponentiel.

Limites de débit

L'API est limitée à 120 requêtes par minute et par clé (fenêtre glissante). Au-delà, l'API renvoie un statut 429. Chaque réponse authentifiée expose les en-têtes suivants :

En-tête	Description
`RateLimit-Limit`	Nombre maximal de requêtes autorisées sur la fenêtre courante.
`RateLimit-Remaining`	Nombre de requêtes restantes sur la fenêtre courante.
`Retry-After`	Délai en secondes avant de pouvoir réessayer (sur réponse 429).

Gérer les 429

En cas de 429, attendez la durée indiquée par Retry-After puis réessayez avec un délai exponentiel et une gigue (jitter). Évitez de réémettre immédiatement la requête en boucle.