---
title: Bases de l'API
description: URL de base, permissions des clés API, liste des erreurs, limites de débit, clés d'idempotence et pagination de l'API BillionSend.
seo:
  title: Authentification et erreurs de l'API
ai:
  exclude: true
---

Les pages de points d'accès de la [référence de l'API](/docs/fr/api-reference) sont générées à partir des définitions de routes de l'API. La [spécification OpenAPI 3.1](/docs/api.openapi.json) est la même source, dans un seul fichier JSON.

L'API est compatible avec l'API Resend : mêmes chemins, mêmes formats de requête et d'erreur. Appelez-la depuis les [SDK](/docs/fr/sdks) BillionSend ou en HTTP brut.

## URL de base

`https://api.billionsend.com`

## Authentification

Envoyez dans chaque requête une clé API créée sous **Clés API** dans le tableau de bord :

```
Authorization: Bearer bs_...
```

Une clé absente ou mal formée répond `401 missing_api_key`, une clé incorrecte `401 invalid_api_key`.

Une clé a un niveau de permission :

- **Accès complet** peut utiliser tous les points d'accès.
- **Envoi uniquement** ne peut qu'envoyer. Tout ce qui est en dehors de `/emails` répond `403 restricted_api_key`, de même que `GET /emails`, `GET /emails/{id}`, `GET /emails/metrics`, `DELETE /emails/{id}` et tous les points d'accès `/emails/receiving`, car ils renvoient du contenu stocké.

Une clé peut aussi être limitée à **un domaine** ou à **une [boîte de réception](/docs/fr/inboxes)**. Une clé limitée à un domaine travaille à l'intérieur de ce domaine : elle n'envoie que depuis lui, ne lit que ses e-mails, ne voit et ne modifie que lui sous `/domains`, et répond `403 restricted_api_key` pour tout ce qui appartient à l'équipe entière (webhooks, listes de suppression, templates, propriétés de contact, `/usage`, `/deliverability`, vérifications, `POST /domains`) ; voir [Clés API](/docs/fr/api-keys). Une clé que vous créez avec l'API n'est jamais plus large que la clé qui l'a créée.

Une équipe peut avoir 25 clés actives. Les actions qui exigent une clé créée par un propriétaire ou un administrateur sont listées sous [Rôles dans l'équipe](/docs/fr/team-roles).

## Erreurs

Chaque erreur a cette forme :

```json
{ "statusCode": 422, "name": "validation_error", "message": "..." }
```

| Statut et nom | Signification |
| --- | --- |
| `400 invalid_parameter` | Le corps n'est pas du JSON valide. |
| `401 missing_api_key` / `invalid_api_key` | Pas de clé, ou une clé incorrecte. |
| `403 restricted_api_key` | La permission ou la portée de la clé ne l'autorise pas. |
| `403 forbidden` | Votre rôle ou votre clé n'autorise pas cette action. |
| `403 plan_limit_reached` | Vous avez atteint une limite de votre forfait. Voir [Forfaits et limites](/docs/fr/billing). |
| `403 sending_paused` | L'envoi est suspendu parce que votre taux de rebonds ou de plaintes est trop élevé. |
| `404 not_found` | Le point d'accès, ou ce que vous avez demandé, n'existe pas. |
| `409 invalid_idempotent_request` | La clé d'idempotence a été utilisée avec une charge utile différente. |
| `415` | Le corps n'est pas `application/json`. |
| `422 validation_error` | La requête n'est pas valide. Le message en donne la raison. |
| `422 all_recipients_suppressed` | Tous les destinataires sont dans la liste de suppression ou se sont désinscrits. Voir [Listes de suppression](/docs/fr/concepts/suppressions). |
| `429 rate_limit_exceeded` | Trop de requêtes. |
| `429 daily_quota_exceeded` / `monthly_quota_exceeded` | Le quota d'envoi de votre forfait est épuisé. Voir [Forfaits et limites](/docs/fr/billing). |
| `503 service_unavailable` | Le stockage des statistiques n'a pas répondu. L'envoi n'est pas affecté. |

Chaque `429` porte un en-tête `retry-after` : le nombre de secondes à attendre.

Chaque réponse, d'erreur ou non, porte un en-tête `x-request-id` : l'identifiant de la requête, le même que celui qu'elle a sur la page Journaux du tableau de bord. Indiquez-le quand vous nous interrogez sur une requête.

Un destinataire dont le domaine ne pourra jamais recevoir de courrier, comme `x@example.com`, `x@foo.test` ou `x@gmail.con`, est refusé avec `422 validation_error`. Il en va de même pour un nouveau contact à une telle adresse. Pour tester sans écrire à personne, envoyez à `success@simulator.amazonses.com`.

La [réception](/docs/fr/receiving), les [boîtes de réception](/docs/fr/inboxes) et la [sécurité des agents](/docs/fr/agent-safety) ajoutent leurs propres erreurs, que ces pages listent.

## Limites de débit

Chaque clé API peut faire 600 requêtes par minute, et les clés d'une équipe 3 000 en tout. Au-delà de la limite, vous recevez `429 rate_limit_exceeded` et un en-tête `retry-after`. Plus de 20 authentifications échouées par minute depuis une même adresse IP sont refusées de la même façon.

## Idempotence

`POST /emails` et `POST /emails/batch` acceptent un en-tête `Idempotency-Key` de 1 à 256 caractères. C'est aussi le cas des réponses, des transferts et des envois de brouillons des boîtes de réception, ainsi que des réponses et des transferts d'e-mails reçus. Réessayez avec la même clé et la même charge utile : vous obtenez la réponse d'origine au lieu d'un second e-mail. La même clé avec une charge utile différente répond `409`.

## Pagination

Les points d'accès de liste acceptent `limit` (1 à 100, 20 par défaut) et les curseurs `after` et `before`, chacun étant l'identifiant d'un élément d'une page précédente. La réponse contient `has_more`. Les listes sont triées du plus récent au plus ancien :

- `after` prend le dernier identifiant d'une page et renvoie des éléments plus anciens.
- `before` prend le premier identifiant et renvoie des éléments plus récents.

Pour rattraper les nouveautés, passez dans `before` l'identifiant le plus récent que vous avez enregistré.

Quelques listes suivent un autre ordre, que leurs pages de référence indiquent : les fils d'une boîte de réception (activité la plus récente en premier), les e-mails d'un fil (les plus anciens en premier), et les thématiques et les libellés (les plus anciens en premier, tous d'un coup). Un curseur qui ne correspond à aucun élément répond `422 validation_error` (`404` sous `/inboxes`).

## Règles utiles à connaître

- **Pièces jointes** : seul `content` en base64 intégré est accepté. Une URL `path` distante répond `422`. Les pièces jointes totalisent jusqu'à 10 MiB par e-mail, et l'e-mail entier doit rester sous 40 MB. Les programmes et les scripts (`.exe`, `.js`, `.bat` et assimilés, y compris dans un ZIP) sont toujours refusés. Sur une nouvelle équipe, certains types à risque, comme les archives, les pages web et les fichiers Office avec macros, sont acceptés mais attendent une revue avant d'être envoyés.
- **Contacts** : ils appartiennent à l'équipe. Il n'y a pas d'audiences : les points d'accès d'audience fonctionnent comme des alias des [segments](/docs/fr/concepts/segments).
- **Désinscriptions** : elles appartiennent au domaine d'envoi. Voir [Désinscriptions](/docs/fr/concepts/unsubscribes).
- **Destinataires** : `to`, `cc` et `bcc` ensemble acceptent jusqu'à 50 adresses, chacune étant une seule boîte mail. Un envoi dont toutes les adresses `to` sont dans la liste de suppression répond `422 all_recipients_suppressed`.
- **En-têtes** : ils sont soumis à une liste autorisée : tout nom `X-*` (sauf `X-SES-*` et `X-BillionSend-*`), les en-têtes de fil de discussion et de priorité, et la paire `List-Unsubscribe`. Tout autre en-tête répond `422`.
- **Objets** : ils peuvent compter jusqu'à 998 caractères.
- **Points d'accès supplémentaires** : `GET /usage` (forfait, limites et consommation), `DELETE /emails/{id}` et `GET /emails/metrics` ([Statistiques](/docs/fr/concepts/analytics)).
- **Contacts en masse** : `POST /contacts/batch` crée et `POST /contacts/batch/remove` supprime jusqu'à 1 000 contacts en une seule requête. `include=properties,topics` sur les listes de contacts ajoute les propriétés et les thématiques de chaque contact.
- **Suppressions en masse** : elles acceptent jusqu'à 1 000 adresses par requête.
- **Statuts supplémentaires** : les campagnes peuvent être `canceled`.
- **Réception et boîtes de réception** : elles sont en bêta, avec de l'interrogation longue (long-polling) et un flux d'événements en direct pour les nouveaux e-mails. Voir [Réception](/docs/fr/receiving) et [Boîtes de réception](/docs/fr/inboxes).
- **Réglages non pris en charge** : ils sont rejetés avec `422` au lieu d'être ignorés en silence.

## Liens de téléchargement signés

Les e-mails reçus portent des liens de téléchargement du message brut et de ses pièces jointes. Ce sont de simples URL `GET` qui n'exigent aucune clé API, valent une heure et répondent `403` une fois expirées. Demandez de nouveau à l'API un lien à jour. Voir [Réception](/docs/fr/receiving).
