Erreurs

Chaque réponse d'erreur de l'API a la même forme :

{
  "error": {
    "type": "validation_error",
    "code": "unknown_field",
    "message": "Field 'foo' does not exist on object 'contact'.",
    "requestId": "req_8a4f2e10bb55",
    "docUrl": "https://docs.boxioo/errors/unknown_field"
  }
}

Champ	Signification
`type`	Famille générale. Branchez dessus pour la logique de retry/UX.
`code`	Code lisible machine. Contrat stable — branchez dessus pour l'UI.
`message`	Explication lisible. Le format peut changer entre versions.
`requestId`	Corrèle avec le header `X-Request-Id`. À citer dans les tickets support.
`docUrl`	Lien direct vers cette section.

Types

`type`	Plage de statut	Réessayable ?
`authentication_error`	401	Non — corrigez votre clé
`permission_error`	403	Non — obtenez une clé avec le bon scope
`validation_error`	400	Non — corrigez la requête
`not_found_error`	404	Non
`conflict_error`	409	Peut-être — selon le `code`
`rate_limit_error`	429	Oui — respectez `Retry-After`
`api_error`	5xx	Oui — backoff exponentiel

Catalogue des codes

400 · Validation

Code	Signification
`invalid_request`	Corps mal formé ou paramètre obligatoire manquant.
`unknown_field`	Le `systemName` envoyé n'existe pas sur cet objet.
`field_not_editable`	Le champ existe mais `isEditable: false`.
`invalid_field_value`	Type incorrect (string là où un nombre est attendu, etc.).
`invalid_option`	L'id d'option SELECT n'est pas dans l'ensemble du champ.
`invalid_relation`	L'id de l'enregistrement lié n'existe pas dans ce tenant ou mauvais objet cible.
`invalid_user`	L'utilisateur référencé n'est pas membre de ce tenant.
`missing_required_field`	Un champ `isRequired: true` est absent sur un `POST`.
`unsupported_field_type`	FILE / IMAGE / OUTLINE — pas encore exposés via l'API publique.
`payload_too_large`	Le corps de requête dépasse 256 Ko.

401 · Authentification

Code	Signification
`unauthorized`	Générique — pas de clé, ou clé non reconnue.
`invalid_api_key`	Header mal formé, ou clé n'ayant jamais existé.
`api_key_revoked`	La clé a été révoquée dans le dashboard.
`api_key_expired`	La clé a dépassé son `expiresAt`.

403 · Permission

Code	Signification
`forbidden`	Échec de permission générique.
`insufficient_scope`	La clé est valide mais n'a pas le scope requis.
`tenant_mismatch`	Le header `X-Tenant-Id` ne correspond pas au tenant de la clé.
`quota_exceeded`	Un quota par tenant (objets, champs) est atteint.

404 · Introuvable

Code	Signification
`resource_not_found`	L'id d'objet / enregistrement / champ est inconnu dans ce tenant.

409 · Conflit

Code	Signification
`conflict`	Conflit générique.
`duplicate_value`	Un champ unique a déjà cette valeur.
`idempotency_key_conflict`	La clé d'idempotence a été réutilisée avec un corps différent.

429 · Limite de débit

Code	Signification
`rate_limited`	Trop de requêtes sur une fenêtre. Lisez Limitation de débit.

5xx · Serveur

Code	Signification
`internal_error`	Un problème de notre côté. Réessayez, puis alertez-nous.

Stratégie de retry

Pseudo-code pour un client robuste :

async function call<T>(req: Request): Promise<T> {
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch(req);
    if (res.ok) return res.json();
 
    const err = await res.json();
 
    // Échecs permanents — on abandonne
    if (err.error.type === 'validation_error') throw err;
    if (err.error.type === 'permission_error') throw err;
    if (err.error.type === 'authentication_error') throw err;
    if (err.error.type === 'not_found_error') throw err;
 
    // Transitoires — backoff
    if (res.status === 429) {
      const retryAfter = Number(res.headers.get('Retry-After') ?? 1);
      await sleep(retryAfter * 1000);
      continue;
    }
    if (res.status >= 500) {
      await sleep(Math.pow(2, attempt) * 1000);
      continue;
    }
    throw err;
  }
  throw new Error('Retries épuisés');
}

On this page