Tupay

Tapez au moins deux caractères. Les flèches parcourent les résultats, Entrée ouvre le résultat courant, Échap ferme la liste. La touche barre oblique amène à ce champ.

Erreurs

Toutes les erreurs partagent la même forme : error (code machine stable), message (français, destiné à un humain, peut changer sans préavis) et code (le statut HTTP). Branchez vos tests sur error, jamais sur message.

Chaque page d'endpoint indique lesquelles de ces réponses elle peut renvoyer, avec le statut HTTP correspondant.

BadRequestapplication/json

Requête invalide

  • Code machine validation_error

    Un champ du corps ne respecte pas son contrat (422).

    {
  "error": "validation_error",
  "type": "invalid_request",
  "message": "Le montant minimum est de 100 XPF.",
  "code": 422
}
    Langage : json

  • Code machine bad_request

    Corps absent ou illisible, paramètre de requête hors bornes (400).

    {
  "error": "bad_request",
  "type": "invalid_request",
  "message": "Corps JSON invalide.",
  "code": 400
}
    Langage : json

  • Code machine invalid_cursor

    Curseur de pagination qui ne se résout pas (400).

    {
  "error": "invalid_cursor",
  "type": "invalid_request",
  "message": "Le curseur « starting_after » ne désigne aucun élément de cette collection : « 8f14e45f-ceea-4c1a-9b7d-2a3f6c8e01b4 ». Reprenez le parcours depuis le début.",
  "code": 400
}
    Langage : json

  • Code machine missing_idempotency_key

    En-tête Idempotency-Key absent sur une opération qui l'exige (400).

    {
  "error": "missing_idempotency_key",
  "type": "invalid_request",
  "message": "Header Idempotency-Key obligatoire.",
  "code": 400
}
    Langage : json
    • errorchaînerequis

      Code machine stable, en snake_case anglais.

    • typechaînerequis
      valeurs : invalid_request, authentication, permission, not_found, conflict, idempotency, rate_limit, provider, api

      Classe de l'erreur, dans un ensemble fermé.

      invalid_request : l'appel est mal formé ou hors bornes, corrigez la requête. authentication : aucune identité valide. permission : identité valide, opération refusée. not_found : la ressource n'existe pas, ou pas pour vous. conflict : l'état courant interdit l'opération, ne retentez pas à l'identique. idempotency : le refus porte sur la clé d'idempotence, pas sur la requête. rate_limit : trop d'appels. provider : le prestataire bancaire a refusé ou n'a pas répondu. api : incident de notre côté, rien à corriger chez vous.

    • messagechaînerequis

      Destiné à un humain, toujours en français.

    • codeentierrequis

      Statut HTTP, repris dans le corps par commodité.

UnsupportedVersionapplication/json

Version d'API inconnue

  • Code machine unsupported_version

    L'en-tête Tupay-Version désigne une version non publiée. Reprise : employez une version de la liste, ou retirez l'en-tête pour laisser s'appliquer celle de votre clé.

    {
  "error": "unsupported_version",
  "type": "invalid_request",
  "message": "Version d’API inconnue. Versions publiées : 2026-01-01.",
  "code": 400
}
    Langage : json
    • errorchaînerequis

      Code machine stable, en snake_case anglais.

    • typechaînerequis
      valeurs : invalid_request, authentication, permission, not_found, conflict, idempotency, rate_limit, provider, api

      Classe de l'erreur, dans un ensemble fermé.

      invalid_request : l'appel est mal formé ou hors bornes, corrigez la requête. authentication : aucune identité valide. permission : identité valide, opération refusée. not_found : la ressource n'existe pas, ou pas pour vous. conflict : l'état courant interdit l'opération, ne retentez pas à l'identique. idempotency : le refus porte sur la clé d'idempotence, pas sur la requête. rate_limit : trop d'appels. provider : le prestataire bancaire a refusé ou n'a pas répondu. api : incident de notre côté, rien à corriger chez vous.

    • messagechaînerequis

      Destiné à un humain, toujours en français.

    • codeentierrequis

      Statut HTTP, repris dans le corps par commodité.

Unauthorizedapplication/json

Clé absente, invalide ou révoquée

  • Code machine unauthorized

    Aucune identité valide n'a pu être établie.

    {
  "error": "unauthorized",
  "type": "authentication",
  "message": "Authentification requise.",
  "code": 401
}
    Langage : json
    • errorchaînerequis

      Code machine stable, en snake_case anglais.

    • typechaînerequis
      valeurs : invalid_request, authentication, permission, not_found, conflict, idempotency, rate_limit, provider, api

      Classe de l'erreur, dans un ensemble fermé.

      invalid_request : l'appel est mal formé ou hors bornes, corrigez la requête. authentication : aucune identité valide. permission : identité valide, opération refusée. not_found : la ressource n'existe pas, ou pas pour vous. conflict : l'état courant interdit l'opération, ne retentez pas à l'identique. idempotency : le refus porte sur la clé d'idempotence, pas sur la requête. rate_limit : trop d'appels. provider : le prestataire bancaire a refusé ou n'a pas répondu. api : incident de notre côté, rien à corriger chez vous.

    • messagechaînerequis

      Destiné à un humain, toujours en français.

    • codeentierrequis

      Statut HTTP, repris dans le corps par commodité.

Forbiddenapplication/json

Opération interdite dans ce contexte

  • Code machine forbidden

    Identité valide, mais l'opération lui est refusée.

    {
  "error": "forbidden",
  "type": "permission",
  "message": "Accès refusé.",
  "code": 403
}
    Langage : json
    • errorchaînerequis

      Code machine stable, en snake_case anglais.

    • typechaînerequis
      valeurs : invalid_request, authentication, permission, not_found, conflict, idempotency, rate_limit, provider, api

      Classe de l'erreur, dans un ensemble fermé.

      invalid_request : l'appel est mal formé ou hors bornes, corrigez la requête. authentication : aucune identité valide. permission : identité valide, opération refusée. not_found : la ressource n'existe pas, ou pas pour vous. conflict : l'état courant interdit l'opération, ne retentez pas à l'identique. idempotency : le refus porte sur la clé d'idempotence, pas sur la requête. rate_limit : trop d'appels. provider : le prestataire bancaire a refusé ou n'a pas répondu. api : incident de notre côté, rien à corriger chez vous.

    • messagechaînerequis

      Destiné à un humain, toujours en français.

    • codeentierrequis

      Statut HTTP, repris dans le corps par commodité.

NotFoundapplication/json

Ressource inexistante, hors de votre périmètre, ou appartenant à l'AUTRE MODE. Nous renvoyons 404 plutôt que 403 pour ne pas confirmer l'existence de ce qui ne vous appartient pas.

  • Code machine not_found

    Inexistante, ou appartenant à un autre marchand.

    {
  "error": "not_found",
  "type": "not_found",
  "message": "Ressource introuvable.",
  "code": 404
}
    Langage : json
    • errorchaînerequis

      Code machine stable, en snake_case anglais.

    • typechaînerequis
      valeurs : invalid_request, authentication, permission, not_found, conflict, idempotency, rate_limit, provider, api

      Classe de l'erreur, dans un ensemble fermé.

      invalid_request : l'appel est mal formé ou hors bornes, corrigez la requête. authentication : aucune identité valide. permission : identité valide, opération refusée. not_found : la ressource n'existe pas, ou pas pour vous. conflict : l'état courant interdit l'opération, ne retentez pas à l'identique. idempotency : le refus porte sur la clé d'idempotence, pas sur la requête. rate_limit : trop d'appels. provider : le prestataire bancaire a refusé ou n'a pas répondu. api : incident de notre côté, rien à corriger chez vous.

    • messagechaînerequis

      Destiné à un humain, toujours en français.

    • codeentierrequis

      Statut HTTP, repris dans le corps par commodité.

Conflictapplication/json

État incompatible avec l'opération

  • Code machine conflict

    L'état courant de la ressource interdit l'opération.

    {
  "error": "conflict",
  "type": "conflict",
  "message": "Cette transaction est déjà intégralement remboursée.",
  "code": 409
}
    Langage : json

  • Code machine idempotency_key_reuse

    Clé déjà employée pour une AUTRE requête (409). Reprise : choisissez une nouvelle clé. Aucun des deux corps n'a été appliqué.

    {
  "error": "idempotency_key_reuse",
  "type": "idempotency",
  "message": "Cette clé d’idempotence a déjà servi pour une requête différente. Choisissez-en une nouvelle : rejouer une clé ne vaut que pour la requête exacte qui l’a créée.",
  "code": 409
}
    Langage : json

  • Code machine idempotency_in_progress

    Une requête portant la même clé est encore en cours (409). Reprise : retentez la même requête à l'identique dans un instant. Aucune seconde ressource n'a été créée.

    {
  "error": "idempotency_in_progress",
  "type": "idempotency",
  "message": "Une requête portant cette clé est encore en cours. Retentez le même appel, avec la même clé, dans un instant.",
  "code": 409
}
    Langage : json
    • errorchaînerequis

      Code machine stable, en snake_case anglais.

    • typechaînerequis
      valeurs : invalid_request, authentication, permission, not_found, conflict, idempotency, rate_limit, provider, api

      Classe de l'erreur, dans un ensemble fermé.

      invalid_request : l'appel est mal formé ou hors bornes, corrigez la requête. authentication : aucune identité valide. permission : identité valide, opération refusée. not_found : la ressource n'existe pas, ou pas pour vous. conflict : l'état courant interdit l'opération, ne retentez pas à l'identique. idempotency : le refus porte sur la clé d'idempotence, pas sur la requête. rate_limit : trop d'appels. provider : le prestataire bancaire a refusé ou n'a pas répondu. api : incident de notre côté, rien à corriger chez vous.

    • messagechaînerequis

      Destiné à un humain, toujours en français.

    • codeentierrequis

      Statut HTTP, repris dans le corps par commodité.

RateLimitedapplication/json

100 req/min par marchand dépassées

  • Code machine rate_limit_exceeded

    Plafond de requêtes atteint. Réessayez après une pause.

    {
  "error": "rate_limit_exceeded",
  "type": "rate_limit",
  "message": "Trop de requêtes. Réessayez dans un instant.",
  "code": 429
}
    Langage : json
    • errorchaînerequis

      Code machine stable, en snake_case anglais.

    • typechaînerequis
      valeurs : invalid_request, authentication, permission, not_found, conflict, idempotency, rate_limit, provider, api

      Classe de l'erreur, dans un ensemble fermé.

      invalid_request : l'appel est mal formé ou hors bornes, corrigez la requête. authentication : aucune identité valide. permission : identité valide, opération refusée. not_found : la ressource n'existe pas, ou pas pour vous. conflict : l'état courant interdit l'opération, ne retentez pas à l'identique. idempotency : le refus porte sur la clé d'idempotence, pas sur la requête. rate_limit : trop d'appels. provider : le prestataire bancaire a refusé ou n'a pas répondu. api : incident de notre côté, rien à corriger chez vous.

    • messagechaînerequis

      Destiné à un humain, toujours en français.

    • codeentierrequis

      Statut HTTP, repris dans le corps par commodité.

BaasErrorapplication/json

Le prestataire bancaire a refusé l'opération

  • Code machine bad_gateway

    Refus venu du prestataire, pas de Tupay. Reprise : réessayez.

    error valait autrefois le code du prestataire lui-même (card_declined, insufficient_funds…). Il vaut désormais toujours bad_gateway, et le code d'origine part dans providerCode. Ce champ est OBSERVABLE mais pas stable : il ne fait pas partie de notre contrat, ne branchez pas dessus.

    {
  "error": "bad_gateway",
  "type": "provider",
  "message": "Le prestataire bancaire n’a pas pu traiter la demande. Réessayez dans un instant ; si le refus persiste, le code du prestataire est indiqué dans « providerCode ».",
  "code": 502,
  "providerCode": "card_declined"
}
    Langage : json
    • errorchaînerequis

      Code machine stable, en snake_case anglais.

    • typechaînerequis
      valeurs : invalid_request, authentication, permission, not_found, conflict, idempotency, rate_limit, provider, api

      Classe de l'erreur, dans un ensemble fermé.

      invalid_request : l'appel est mal formé ou hors bornes, corrigez la requête. authentication : aucune identité valide. permission : identité valide, opération refusée. not_found : la ressource n'existe pas, ou pas pour vous. conflict : l'état courant interdit l'opération, ne retentez pas à l'identique. idempotency : le refus porte sur la clé d'idempotence, pas sur la requête. rate_limit : trop d'appels. provider : le prestataire bancaire a refusé ou n'a pas répondu. api : incident de notre côté, rien à corriger chez vous.

    • messagechaînerequis

      Destiné à un humain, toujours en français.

    • codeentierrequis

      Statut HTTP, repris dans le corps par commodité.