Erreurs

Le format

Toute erreur suit le format Problem Details (RFC 9457), avec le type de contenu application/problem+json :

{
  "type": "https://docs.deltia.co/developers/api/errors#not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No such resource, or it is outside the scope of this key.",
  "instance": "/api/v1/crm/entities/societes/records/8f2…",
  "requestId": "4b1f…"
}

• type pointe sur la section de cette page qui correspond à l'erreur. La fin de l'URL, après #, est le slug : c'est lui qu'un programme doit tester, pas le texte.
• requestId est le même que l'en-tête X-Request-Id. Citez-le si vous contactez le support.
• Une erreur de validation ajoute errors, une entrée par champ refusé : path, code, message, et parfois allowed, les valeurs acceptées.
• Une erreur 429 ajoute retryAfter, en secondes, repris dans l'en-tête Retry-After.

Les textes title et detail sont en anglais et ne révèlent jamais le fonctionnement interne de Deltia.

invalid-api-key

401. L'en-tête Authorization manque, n'est pas au format Bearer <secret> (le mot Bearer dans n'importe quelle casse), ou le secret ne correspond à aucune clé de cet espace. Une clé valide présentée sur l'adresse d'un autre espace reçoit aussi cette réponse.

api-key-expired

401. La clé a dépassé sa date d'expiration. Créez-en une nouvelle.

api-key-revoked

401. La clé a été révoquée. Une révocation est définitive : créez une nouvelle clé.

api-disabled

403. Le module API n'est pas activé sur cet espace. Les clés existantes sont conservées et fonctionneront de nouveau à sa réactivation.

permission-denied

403. La clé n'a pas le droit demandé : le verbe create ou update sur cette entité, la lecture des devis ou des factures, ou tout accès au CRM. Les droits d'une clé sont figés : il faut une nouvelle clé.

entity-operation-disabled

403. La clé a le verbe, mais l'entité a désactivé l'opération dans le CRM (création ou modification coupée par un administrateur), ou exige à la création un champ que la clé ne peut pas écrire (voir Créer et modifier). C'est la configuration de l'entité qu'il faut changer, pas la clé.

record-owner-forbidden

403. L'entité réserve la modification de ses fiches à leur créateur, et cette fiche n'a pas été créée par la clé. Une fiche créée par une autre clé, même celle qu'elle remplace, compte comme créée par quelqu'un d'autre. Seul un administrateur de l'organisation peut la modifier depuis l'application.

not-found

404. La ressource n'existe pas, ou elle est hors de portée de la clé : entité absente de sa matrice, fiche ou document hors de ses périmètres, identifiant mal formé. L'API ne distingue pas ces cas, pour ne rien confirmer.

pdf-not-available

404. Le document existe et la clé le voit, mais aucun PDF n'a encore été produit : typiquement une facture pas encore transmise à la plateforme de facturation électronique, ou un brouillon.

bad-request

400. La requête est mal formée : corps qui n'est pas du JSON, ou curseur que l'API n'a pas émis. Repartez du nextCursor de la dernière réponse, sans le modifier.

validation

400. Un ou plusieurs champs sont invalides. errors détaille chaque champ : paramètre de liste hors bornes, statut inconnu, champ inconnu ou en lecture seule, champ obligatoire manquant ou effacé, périmètre à choisir. Voir Créer et modifier.

method-not-allowed

405. L'endpoint n'accepte pas cette méthode HTTP. L'API n'a pas de DELETE.

unsupported-media-type

415. Un POST ou un PATCH sans l'en-tête Content-Type: application/json.

payload-too-large

413. Le corps d'un POST ou d'un PATCH dépasse 1 Mio. Aucune écriture n'en a besoin : un fichier ne passe pas par le corps d'une fiche.

conflict

409. La même fiche a été modifiée au même instant par quelqu'un d'autre. Relisez-la, puis rejouez votre modification.

rate-limited

429. Le quota de la clé est épuisé pour la minute en cours. Attendez le nombre de secondes indiqué par Retry-After, puis reprenez. Chaque clé a son propre quota.

Un appel refusé par le quota n'apparaît pas dans l'onglet Activité de la clé. Les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset indiquent où en est la clé.

upstream-error

502. Un système dont dépend l'espace n'a pas répondu, typiquement la plateforme de facturation électronique. Réessayez plus tard.

internal

500. Une erreur de notre côté. Elle nous est signalée automatiquement ; si elle persiste, contactez le support en citant requestId.