Erreurs et limites
Identifiez les erreurs et prévoyez des reprises adaptées.
Format des erreurs
{
"error": {
"code": "insufficient_balance",
"message": "Solde prépayé insuffisant. Rechargez votre compte."
}
}Utilisez le statut HTTP et error.code pour votre logique. error.message fournit une explication lisible.
Codes HTTP
| HTTP | Code fréquent | Action |
|---|---|---|
| 400 | invalid_filter, invalid_package, invalid_order | Corrigez les paramètres avant de réessayer. |
| 401 | invalid_api_key, agency_login_required | Vérifiez l’en-tête Bearer et la validité de la clé. |
| 402 | insufficient_balance | Rechargez le solde agence. Aucun débit sur cet échec. |
| 403 | scope_required, agency_suspended | Vérifiez les permissions ou contactez l’administrateur. |
| 404 | package_not_found, not_found | Vérifiez le code ou l’identifiant de la ressource. |
| 409 | quote_expired, price_changed | Demandez un nouveau devis et confirmez son montant. |
| 409 | idempotency_conflict | Réutilisez le contenu original de la commande. |
| 409 | esim_not_ready | Poursuivez le suivi de livraison. |
| 429 | rate_limited | Réduisez la fréquence et espacez les reprises. |
| 502 / 503 | provider_mismatch, supplier_unavailable | Vérifiez l’état de la commande avant toute nouvelle tentative. |
Limites de débit
| Opération | Limite |
|---|---|
| Appels par clé API | 1 800 par tranche de 15 minutes. |
| Création de devis | 120 par agence et par tranche de 15 minutes. |
| Création de commandes | 120 par agence et par tranche de 15 minutes. |
Plusieurs clés d’une même agence partagent les limites de création. Utilisez un délai de reprise progressif avec une variation aléatoire et évitez les boucles immédiates. Aucun en-tête Retry-After n’est garanti par cette version.
Reprises et dépannage
Une lecture échoue : attendez puis réessayez avec un délai progressif.
Une création de commande expire côté réseau : réessayez avec la même clé d’idempotence et le même contenu.
La commande passe à needs_review : conservez sa référence et demandez une vérification à l’équipe eSIMY.
Une recharge reste incertaine : vérifiez l’opération existante dans le portail, sans lancer un nouveau paiement.
Pour un diagnostic, transmettez l’identifiant de commande, le code d’erreur et l’heure de l’appel à votre interlocuteur eSIMY. Ne transmettez pas votre clé API ni les codes d’activation eSIM.