Erreurs

colis a trois familles d’erreurs, chacune avec un code stable sur lequel brancher plutôt que sur un statut HTTP ou le texte d’un message.

Dans la bibliothèque : ColisError

Tout ce que lève @colis/core est une ColisError, avec un code et l’erreur d’origine dans cause :

import { isColisError } from '@colis/core'

try {
  await store.upload(file)
} catch (error) {
  if (isColisError(error)) console.error(error.code, error.message, error.cause)
  throw error
}

INVALID_CONFIG, INVALID_SYNC_CODE, INVALID_KEY, INVALID_BODY, MISSING_CONTENT_LENGTH et FILE_TOO_LARGE sont levées avant qu’un seul octet ne parte : un code absurde collé dans un champ coûte une comparaison, pas une requête.

Une clé absente n’est pas une erreur : get(), head() et getSnapshot() renvoient null, et delete() sur une clé absente réussit sans bruit.

Sur le fil : TransferError

Les routes du protocole répondent { error: { code, message } }, et le client de @colis/protocol (donc la CLI, les hooks React et le nœud n8n) lève une TransferError avec ce code : INVALID_REQUEST, INVALID_SYNC_CODE, UNAUTHORIZED, NOT_FOUND, CODE_TAKEN, SNAPSHOT_TOO_NEW, TOO_LARGE, INTERNAL.

import { isTransferError } from '@colis/protocol'

if (isTransferError(error) && error.code === 'NOT_FOUND') {
  // code inconnu ou expiré : les deux sont indiscernables, exprès
}

Sur la page de livraison

Ses routes propres gardent la même forme de réponse, avec quelques codes en plus :

Les routes des comptes ajoutent les leurs :

La formule Pro ajoute les siens :

{
  "error": {
    "code": "PLAN_LIMIT",
    "message": "Ce fichier dépasse 100 Mo, la limite de la formule gratuite. La formule Pro accepte jusqu’à 2 Go.",
    "details": { "limit": "size", "max": 104857600, "pro": 2147483648 }
  }
}

Les messages de ces routes sont en français, prêts à être affichés au client.

Dans la CLI

La CLI sort avec le code 1 à chaque échec, et distingue ce qu’il faut faire :

• une erreur d’usage (commande inconnue, fichier absent, bucket non configuré) s’affiche avec une piste de correction en dessous ;
• une erreur du protocole ou de la bibliothèque s’affiche avec son code, par exemple NOT_FOUND: Unknown or expired code. ;
• INVALID_CONFIG rappelle que colis config montre ce que la configuration a résolu ;
• PLAN_LIMIT rappelle que la formule Pro va plus loin : colis compte pro.

En cas de doute, colis verifier effectue chaque opération et dit laquelle échoue.