# Requêtes & erreurs

> La forme des requêtes et des réponses de l'API Ora, la signification de chaque erreur, et les limites de débit.

### Requêtes et réponses

- **JSON en entrée, JSON en sortie.** Envoyez `Content-Type: application/json` avec un corps, et seulement avec un corps.
- **Enveloppe.** Chaque réponse contient `"success": true` ou `"success": false`. Vérifiez ce champ, pas seulement le code de statut.
- **Les montants en tokens** sont des unités de base brutes, sous forme de *chaînes de caractères* décimales, car ils dépassent la capacité des nombres JavaScript : `"250000000000"`. Divisez par 10 à la puissance du nombre de décimales du token pour les afficher (la plupart des tokens de launchpads Solana utilisent 6 décimales, les tokens EVM 18).
- **Montants natifs.** Les entrées nommées `…Sol` sont de simples nombres décimaux de l'actif de gas de la chain (`0.5`). Dans les réponses, les montants natifs bruts sont en lamports sur Solana et en wei sur les chains EVM.
- **Adresses.** Les adresses Solana sont en base58, les adresses EVM en hexadécimal `0x`. Dans un chemin, `{address}` et `{mint}` désignent le mint (Solana) ou le contrat (EVM) d'un token.
- **ID de requête.** Chaque réponse porte un en-tête `X-Request-ID`. Envoyez le vôtre (un UUID v4) pour relier un appel à vos logs ; Ora le transmet à chaque service sollicité.
- **Les horodatages** sont au format ISO 8601, en UTC.

### Erreurs

Un appel en échec répond avec `"success": false` et un champ `error`. Quand Ora relaie l'échec de l'un de ses services, `error` est un court code de référence (comme `M4K8T`) et `message` donne la raison en clair.

```json
{
  "success": false,
  "error": "M4K8T",
  "message": "…readable reason…"
}
```

| Statut | Signification | Que faire |
|---|---|---|
| `400` | Le corps ou un paramètre est invalide. | Lisez `error` et `message` : ils nomment le champ concerné. Ne réessayez pas à l'identique. |
| `401` | Pas de clé, une clé mal formée, ou une clé qui a été renouvelée ou révoquée. | Vérifiez l'en-tête et la clé. Ne réessayez pas en boucle : les clés refusées sont soumises à une limite de débit par IP. |
| `403` | L'accès API est désactivé sur le compte. | Demandez au support Ora d'activer l'accès API. |
| `404` | Introuvable, ou pas à vous. Ora ne révèle jamais si une ressource qui ne vous appartient pas existe. | Vérifiez l'ID ou l'adresse, et qu'il appartient bien à votre compte. |
| `409` | La ressource n'est pas dans un état qui le permet (pas encore lancée, déjà en cours...). | Lisez l'état, puis agissez. |
| `429` | Limite de débit atteinte. | Ralentissez : voir [Limites de débit](#rate-limits). |
| `502` | Un service derrière l'API a échoué. | Réessayez avec une attente croissante. Si le problème persiste, envoyez le code `error` et le `X-Request-ID` au support Ora. |
| `503` | Temporairement indisponible (une dépendance est en panne ou saturée). | Réessayez avec une attente croissante. |

> **Warning:** **Les écritures ne sont pas idempotentes.** Un `502` ou un timeout sur un achat, une vente ou un lancement ne signifie pas que rien ne s'est passé. Lisez l'état (positions, trades, le flux du token) avant de réessayer une écriture.

### Limites de débit

| Budget | Limite | Compté par | Couvre |
|---|---|---|---|
| Requêtes API | 100 par minute | Compte | Toutes les requêtes faites avec votre clé, flux compris (une par connexion). Distinct du budget propre à l'app : un script très actif ne ralentit jamais votre session dans l'app. |
| Clés refusées | 20 par minute | Adresse IP | Les requêtes dont la clé est mal formée ou inconnue (`401`). Au-delà, elles reçoivent un `429`. |

Les fenêtres sont des fenêtres fixes d'une minute. Un `429` ne porte pas d'en-tête `Retry-After` : attendez, puis réessayez avec une attente exponentielle qui commence à 1 seconde et plafonne à 60. Étalez les traitements par lots dans le temps plutôt que de les envoyer en rafale.

```js title="retry.mjs"
export async function withRetry(fn, tries = 6) {
  for (let i = 0; ; i++) {
    try { return await fn(); }
    catch (err) {
      const retryable = err.status === 429 || err.status === 502 || err.status === 503;
      if (!retryable || i + 1 >= tries) throw err;
      await new Promise((r) => setTimeout(r, Math.min(60_000, 1000 * 2 ** i)));
    }
  }
}
// Reads only. Before retrying a write, check what already happened.
```