Erreurs

Toute erreur a la même forme :

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Le champ url est obligatoire.",
    "param": "url",
    "doc_url": "https://docs.ophelix.fr/erreurs#parameter_invalid",
    "request_id": "req_…"
  }
}

Comparez code dans votre programme : il est stable. message s’adresse à un humain et peut changer. Une erreur de validation ajoute errors, la liste de tous les champs fautifs. Transmettez request_id au support : chaque réponse le répète dans l’en-tête Request-Id.

doc_url mène à l’ancre du code, sur cette page.

Requête invalide

parameter_invalid

Un champ ne convient pas. param le nomme, errors liste tous les champs fautifs. Corrigez la requête.

parameter_missing

Un champ obligatoire manque. param le nomme, errors liste tous les champs fautifs.

parameters_exclusive

Deux paramètres s’excluent, par exemple starting_after et ending_before. Gardez-en un.

resource_missing

L’objet n’existe pas, n’appartient pas à votre organisation ou vit dans l’autre mode. Une clé de test ne voit pas un objet de production. Un préfixe faux répond la même chose.

route_not_found

Cette route n’existe pas. Vérifiez le chemin dans la référence.

method_not_allowed

La route existe, pas avec cette méthode. L’en-tête Allow dit lesquelles conviennent.

api_version_invalid

Ophelix-Version porte une version inconnue. Voir Conventions.

conflict

L’objet n’est pas dans le bon état pour cette action : une facture déjà signée ne se modifie plus, un retour simulé arrive hors de son cycle. Relisez l’objet.

card_unreadable

La carte ne se lit pas. En mode test, le scénario vitale_unreadable donne ce résultat.

card_blocked

La carte est bloquée après trois codes faux. En mode test, le scénario cps_blocked donne ce résultat.

token_invalid

Le lien ou le jeton a expiré ou a déjà servi. Demandez-en un nouveau depuis le tableau de bord.

pairing_code_invalid

Le code d’appairage est inconnu, expiré, annulé ou déjà consommé. Créez-en un autre. Voir Postes.

pairing_transfer_required

Ce poste appartient déjà à une organisation. Confirmez le rattachement par POST /v1/workstation-pairing-codes/{id}/confirm-transfer, ou annulez le code.

agent_outdated

L’agent de poste est trop ancien. Mettez-le à jour : minimum_version dit le minimum. Le code d’appairage reste valable.

claim_invalid

La facture enfreint au moins une règle et reste un brouillon. violations liste tout ce qui ne va pas, avec rule, message, param et line, l’identifiant de la prestation visée, ou null. Voir Factures.

Authentification

authentication_required

Aucune clé n’accompagne la requête. Passez Authorization: Bearer sk_test_….

session_expired

La session du tableau de bord a expiré. Rechargez la page. Ce code ne concerne pas une clé d’API.

invalid_api_key

Cette clé n’existe pas ou a été révoquée. Voir Clés d’API.

api_key_expired

Cette clé a atteint son échéance, souvent la fin du recouvrement après une rotation. Utilisez sa remplaçante.

invalid_credentials

Adresse ou mot de passe faux, à la connexion au tableau de bord. Ce code ne concerne pas une clé d’API.

invalid_workstation_token

Le jeton du poste est inconnu. L’agent revient à l’appairage.

Permission

permission_denied

Votre rôle ne permet pas cette action dans le tableau de bord.

insufficient_scope

La clé est valable, mais elle ne porte pas le droit que la route demande : par exemple events:read ou claims:write. Une écriture n’implique pas la lecture. Créez une clé restreinte avec le droit manquant, ou utilisez une clé secrète.

two_factor_required

Le tableau de bord demande un second facteur pour ce compte. L’API, elle, ne passe que par les clés.

email_not_verified

Confirmez votre adresse avant de créer une clé.

live_not_activated

La production n’est pas ouverte pour cette organisation. Restez en mode test.

test_mode_only

Cette route ne sert qu’en mode test : prenez une clé sk_test_….

workstation_revoked

Ce poste a été révoqué. Pour le réutiliser, appairez-le avec un nouveau code.

Débit

rate_limit_exceeded

Trop de requêtes. Attendez le délai de Retry-After. Voir Conventions.

Idempotence

idempotency_key_reused

Cette clé d’idempotence a déjà servi avec un autre corps. Générez-en une nouvelle. Voir Idempotence.

idempotency_key_in_progress

La première requête tourne encore. Réessayez un instant plus tard, avec la même clé.

Erreur de l’API

engine_unavailable

Le moteur de facturation ne répond pas. Tant qu’il n’est pas raccordé, les écritures de facture répondent ce code en production. Rejouez avec la même clé d’idempotence.

workstation_ca_unavailable

Le certificat du poste n’a pas pu se signer. Réessayez : le code d’appairage n’est pas consommé.

api_error

Erreur de notre côté. Rejouez avec la même clé d’idempotence. Si elle persiste, transmettez request_id au support.