> Pour les agents IA : guide de configuration étape par étape — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md), index de la documentation — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# Erreurs et limites

Limites de requêtes, délais d'attente et codes d'erreur de la passerelle. Pour chaque réponse, nous indiquons quand elle survient et quoi faire : relancer la requête ou la corriger.

## Limites

Les chiffres proviennent du champ `limits` de la réponse `GET /v1/capabilities` : les valeurs y sont toujours à jour.

| Limite | Valeur | En cas de dépassement |
| --- | --- | --- |
| Requêtes par minute par clé | 120, fenêtre de 60 s à partir de la première requête | `429 rate_limit_exceeded` et en-tête `Retry-After` ; les refus 5xx de la passerelle ne consomment pas le quota |
| Requêtes simultanées du compte | limitées | les requêtes excédentaires attendent en file ; si elles n'aboutissent pas — `429 queue_timeout` |
| Taille du corps de la requête | 16 MiB | `413` |
| Longueur de la réponse | [par modèle — tableau ci-dessous](https://gate.joingonka.ai/fr/docs/errors#max-tokens) | au-delà du plafond du modèle — réduit au plafond, sans erreur |
| Clés enfants | jusqu'à 50 par clé de gestion, jusqu'à 120 requêtes par minute chacune | augmenter les plafonds — via le support |

### Longueur de réponse par modèle

Sans `max_tokens`, la passerelle applique une valeur par défaut : sans streaming — plus courte, pour que la réponse tienne dans les timeouts ; en streaming — le plafond du modèle. `max_completion_tokens` — même champ.

| `model` | Plafond | Sans streaming | En streaming |
| --- | ---: | ---: | ---: |
| `MiniMaxAI/MiniMax-M2.7` | 8192 | 1500 | 8192 |
| `deepseek-ai/DeepSeek-V4-Flash-0731` | 32768 | 1500 | 32768 |
| `zai-org/GLM-5.3-Flash` | 8192 | 3000 | 8192 |

## Timeouts

| Étape | Valeur | Ce qui se passe |
| --- | --- | --- |
| Attente d'une place dans la file | 45 s | `429 queue_timeout` avec en-tête `Retry-After: 1` |
| Début de la réponse du réseau, streaming | 150 s | `504 upstream_timeout` ; une estimation des tokens d'entrée est débitée |
| Début de la réponse du réseau, sans streaming | 150 s | `504 upstream_timeout` ; une estimation des tokens d'entrée est débitée |
| Génération de la réponse | ≈ 300 s | le réseau interrompt la génération : la réponse arrive avec `finish_reason: length` — poursuivez avec la requête suivante |
| Pause entre les chunks du stream | 30 s | le flux se ferme : `finish_reason: stop` dans le chunk `joingonka-stream-stalled` |
| Signal d'activité dans le stream | 15 s | commentaire `: keep-alive` — les clients SSE l'ignorent |
| Ouverture du flux | 30 s | avant ce moment, le refus arrive avec un code de réponse ; après — via le chunk `joingonka-error` |
| Réponse anticipée sans streaming | 90 s | la passerelle renvoie `200` et envoie des espaces toutes les 15 s — le JSON reste valide ; une erreur après cela arrive dans le corps avec le champ `error`, le statut reste `200` |

> **Ce qui est débité en cas de timeout**
>
> Une requête acceptée par le réseau ne peut pas être annulée. Avec `504 upstream_timeout`, l'estimation des tokens d'entrée est débitée, celle des tokens de sortie non ; une nouvelle tentative entraîne un nouveau débit. Un stream interrompu avant le `usage` final est facturé de la même manière. Pour les réponses longues, utilisez `stream: true`.

## Codes d'erreur

Le corps de l'erreur est un objet `error` avec les champs `message, type, code, param` ; certains champs ne sont pas présents sur toutes les erreurs. Fiez-vous au statut et au `type`, vérifiez via `code` : le texte `message` peut changer. Le format Anthropic est décrit dans la section [Format des erreurs Anthropic](https://gate.joingonka.ai/fr/docs/errors#anthropic-errors).

```json
{
  "error": {
    "message": "Model is currently overloaded in the Gonka network",
    "type": "rate_limit_exceeded",
    "code": "upstream_rate_limited"
  }
}
```

| Réponse | Quand | Que faire |
| --- | --- | --- |
| 400 `invalid_request_error` | Corps invalide : `messages` absent, message qui n'est pas un objet, corps qui n'est pas du JSON ; modèle inconnu — avec `param` : `model` et la liste des modèles disponibles dans le texte | Corrigez la requête en suivant le texte de l'erreur |
| 400 `invalid_request_error` `empty_content_after_normalization` | Message vide après normalisation — par exemple, il ne contenait qu'une image | Ajoutez du texte dans le message |
| 400 `invalid_request_error` `web_search_privacy_sanitization_not_supported` | Plugins `web` et `privacy-sanitization` dans une même requête | N'en gardez qu'un seul |
| 400 `invalid_request_error` `previous_response_id_not_supported` `conversation_not_supported` `item_reference_not_supported` `background_not_supported` `hosted_tool_choice_not_supported` | OpenAI Responses : référence à une réponse, un dialogue ou un élément sauvegardé ; mode arrière-plan ; exigence d'un outil intégré | Envoyez l'historique complet dans `input` |
| 400 `api_error` | Le réseau a rejeté les paramètres — par exemple, une valeur `reasoning_effort` hors de sa liste | Corrigez la valeur en suivant le texte de l'erreur |
| 401 `authentication_error` | Clé introuvable, révoquée ou de format inconnu | Vérifiez la clé sur la page [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) |
| 402 `insufficient_funds` | Solde insuffisant pour l'estimation de la requête ; le reste est dans `balance_ngonka` | Rechargez votre solde : [gate.joingonka.ai/billing](https://gate.joingonka.ai/billing) |
| 402 `insufficient_funds` | Requête sans clé ne provenant pas du site (`is_demo: true`) | Fournissez une clé API |
| 402 `child_key_limit_exceeded` | Limite de dépenses de la clé dépassée — journalière, mensuelle ou globale ; les restes sont dans `daily_remaining, monthly_remaining, total_remaining` | Augmentez la limite de la clé sur la page [gate.joingonka.ai/keys](https://gate.joingonka.ai/keys) ou attendez la réinitialisation |
| 403 `forbidden` | Clé d'administration `gm-` dans une requête vers le modèle ; clé API sur une route réservée à l'espace client | Pour les requêtes — clé `jg-` ou `gc-` ; la gestion du compte se fait dans l'espace client |
| 404 `invalid_request_error` `model_not_found` | `GET /v1/models/{model}` : le modèle n'est pas dans le catalogue ou est temporairement masqué | Prenez l'id dans `GET /v1/models` |
| 404 `invalid_request_error` `not_found` `compact_not_supported` | OpenAI Responses : `/v1/responses/{id}` et autres adresses d'état, `/v1/responses/compact` | Conservez l'historique de votre côté ; pour Codex CLI, définissez votre propre id de fournisseur |
| 404 `invalid_request_error` | Chemin inconnu | Vérifiez la méthode, le chemin et l'adresse de base |
| 413 `invalid_request_error` | Corps de la requête au-delà de la limite | Réduisez la requête |
| 415 `invalid_request_error` | Corps non JSON d'après l'en-tête : `Content-Type: application/json` requis | Envoyez `Content-Type: application/json` |
| 429 `rate_limit_exceeded` | Nombre de requêtes par minute par clé dépassé ; dans le corps — `rate_limit` avec `limit, remaining, reset` | Attendez le nombre de secondes indiqué dans `Retry-After` |
| 429 `rate_limit_exceeded` `upstream_rate_limited` | Modèle surchargé sur le réseau Gonka | Réessayez après `Retry-After` ou prenez un autre modèle — [Modèles](https://gate.joingonka.ai/fr/docs/models) |
| 429 `rate_limit_exceeded` `queue_timeout` `queue_full` | Toutes les places vers le réseau sont occupées : file pleine ou attente expirée | Réessayez après `Retry-After` |
| 500 `server_error` | Erreur interne de la passerelle | Réessayez plus tard ; si cela persiste, écrivez au support en joignant `x-request-id` |
| 501 `not_implemented` | `POST /v1/embeddings` : aucun modèle d'embeddings sur le réseau | Utilisez un autre service d'embeddings |
| 502 `api_error` `upstream_unauthorized` | Le fournisseur du réseau a rejeté les identifiants de la passerelle — votre clé est correcte | Réessayez dans une minute |
| 502 `api_error` | Erreur du réseau Gonka ; `code` provient du réseau, s'il l'a envoyé | Réessayez avec une pause ou prenez un autre modèle |
| 503 `model_unavailable` `model_outage` `model_initializing` `model_unstable` `model_not_served` | Modèle actuellement indisponible d'après les sondes du réseau : panne, démarrage, instabilité ou personne ne le sert ; refus immédiat, sans attente | Prenez un autre modèle — le texte de l'erreur vous indiquera lequel ; la liste est dans [Modèles](https://gate.joingonka.ai/fr/docs/models) |
| 503 `service_unavailable` | Aucun nœud disponible | Réessayez plus tard |
| 504 `timeout` `upstream_timeout` | Le réseau a accepté la requête mais n'a pas répondu à temps ; l'estimation des tokens d'entrée a été débitée | Pour les réponses longues — `stream: true` ; une nouvelle tentative entraîne un nouveau débit |

## Erreurs dans un flux ouvert

Tant que le flux n'est pas ouvert, le refus arrive avec un code de réponse classique — comme sans streaming. Une fois ouvert, le statut est déjà `200`, et l'erreur arrive ainsi :

- Chat Completions — chunk `joingonka-error` avec le champ `error`, puis coupure sans `[DONE]`.
- Sans streaming après une réponse précoce — statut `200` et corps avec le champ `error`.
- Anthropic Messages — événement `event: error`, puis le flux se ferme.
- OpenAI Responses — événement `response.failed`, la cause est dans `response.error.code`.
- Legacy Completions — `data: {"error": …}`, puis `[DONE]`.

```text
data: {"id":"joingonka-error","object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[],"error":{"message":"Gonka network error","type":"api_error"}}
```

## Format des erreurs Anthropic

- `POST /v1/messages` répond avec l'enveloppe Anthropic : `{"type": "error", "error": {"type", "message"}}`.
- Les refus de la passerelle conservent le `type` du tableau ci-dessus (`insufficient_funds`, `model_unavailable` et autres) ; le champ `code` n'existe pas dans cette enveloppe — la cause est dans le texte.
- Erreurs de forme de la requête — `invalid_request_error` : messages ou `max_tokens` absents, appel d'outil sans nom, modèle inconnu.
- Chemin inconnu — `not_found_error`, corps trop volumineux — `request_too_large`.

```text
event: error
data: {"type":"error","error":{"type":"timeout","message":"Upstream timeout"}}
```

## Ce qu'il faut réessayer

- Après la pause indiquée dans `Retry-After` : `429`
- Avec une pause croissante — 1, 2, 4 s et ainsi de suite : `500`, `502`, `503 service_unavailable`, `504`
- Avec un autre modèle : `503 model_unavailable`
- Ne pas réessayer sans modifications — corrigez la requête, la clé ou le solde : `400`, `401`, `402`, `403`, `404`, `413`, `415`, `501`

Chaque nouvelle tentative après `504` entraîne un nouveau débit de l'estimation d'entrée ; pour les réponses longues, activez `stream: true`.

Si l'erreur persiste, écrivez au support en joignant `x-request-id` des en-têtes de réponse.