AttendBeacon
Ouvrir l’espace de travail

Concepts

Erreurs

Chaque refus est un problème RFC 9457 avec un code stable. Basez votre logique sur le code ; montrez le détail à une personne.

La forme d’un problème

Quand l’API refuse un appel, elle répond avec un statut de 400 ou plus et un corps application/problem+json, tel que le décrit la RFC 9457 :

JSON
{
  "type": "https://attendbeacon.com/developers/errors#moduleOff",
  "title": "The module is switched off",
  "status": 409,
  "detail": "The Sponsors module is switched off for this event. Its organiser can switch it on under the event's Modules; nothing was deleted.",
  "instance": "/api/v1/events/b3ac0000-0000-4000-8000-000000000001/sponsors",
  "code": "moduleOff",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",
  "module": "sponsors",
  "error": "The Sponsors module is switched off for this event. ..."
}
  • code est ce sur quoi votre logiciel s’appuie. Les codes sont stables : une fois publiés, jamais renommés.
  • detail est une phrase destinée à une personne : affichez-la dans votre journal ou votre interface.
  • type pointe vers la ligne du code dans le tableau ci-dessous.
  • traceId aide le support d’AttendBeacon à retrouver l’appel ; joignez-le à votre demande.
  • Certains codes apportent davantage : scope (l’autorisation qui manque à une clé), module, errors (chaque champ incorrect), etag, taken, sessions.
  • error reprend detail pour les flux créés avant les problem details. Il reste en v1 ; le nouveau code doit lire detail.

Champs incorrects

invalidRequest liste chaque champ avec ce qui ne va pas, pour qu’un formulaire puisse afficher le message à côté du champ :

JSON
{
  "status": 400,
  "code": "invalidRequest",
  "detail": "Some fields are not right; errors names each.",
  "errors": [
    { "field": "startDate", "message": "startDate is a date such as 2026-11-12." },
    { "field": "timeZone", "message": "timeZone is an IANA zone such as Europe/Amsterdam." }
  ]
}

Une inscription refusée désigne aussi le participant, en partant de 0, avec un code indiquant le problème : { "attendee": 0, "field": "email", "code": "notEmail" }.

Quoi réessayer

StatutRéessayer ?
400, 401, 403, 404, 409, 412, 422Non : la même requête sera de nouveau refusée. Corrigez-la d’abord.
429Oui, après le nombre de secondes indiqué par Retry-After. Voir Limites de débit.
500, 502, 503, 504Oui, quelques fois avec une attente croissante, et avec le même Idempotency-Key pour un POST. Voir Idempotence.

Tous les codes

CodeStatutSignification et marche à suivre
invalidKey401No working API key. No key was sent, or it is not one this platform made. Send it as Authorization: Bearer abk_... or in X-Api-Key.
keyExpired401The key has expired. The key's expiry date has passed. Make a new key in the workspace under Integrations, API & MCP.
keyRevoked401The key was revoked. Somebody revoked the key in the workspace. Make a new key.
wrongAudience401A token for another resource. A token an assistant got by signing in works where it was issued for: the MCP server (/mcp) or the REST API (/api/v1).
invalidOrigin403Not from this origin. The MCP server takes browser requests from AttendBeacon's own origin only; servers and command-line clients send no Origin.
missingScope403The key lacks a scope. The key works but may not do this; scope names the scope it needs. Scopes are chosen when a key is made.
peopleScope403Personal data needs people:read. This call is about people by name or address, which needs the people:read scope as well.
notFound404Not found. There is no such resource in this key's workspace. Another workspace's ids read as not found.
eventNotFound404No such event. There is no such event in this key's workspace.
attendeeNotFound404No such attendee. There is no such attendee at this event.
noDoor404No such door. There is no such door at this event.
moduleOff409The module is switched off. The event's organiser switched this feature off under the event's Modules; module names it. Nothing was deleted: switched on again, its data is back.
onlineEvent409An online event has no doors. Check-in and other door features do not apply to an online event.
alreadyCancelled409Already cancelled. The ticket is already cancelled.
clash409The room is taken. Another session is in the room at that time; sessions names it. Send allowClash: true to place it anyway.
slugTaken409The address is taken. Another event already has this slug.
historyNeedsLicence409A licence is needed first. Reopening an earlier edition above the free limit needs its licence, bought in the workspace.
endsCommunity409This would end the community status. A paid ticket ends an event's free community status above the free limit; confirm in the workspace.
codeTaken409The code exists. The event already has a discount code with these letters.
capacityBelowTaken409Capacity below what is sold. The capacity would be lower than the places already taken; taken says how many.
idempotencyKeyInUse409The same request is still running. A request with this Idempotency-Key is still being handled. Wait a moment and send it again.
preconditionFailed412Changed since you read it. If-Match does not name the resource as it is now: somebody changed it. Read it again, then send the change.
idempotencyKeyReused422Idempotency-Key used for another request. This Idempotency-Key was used within 24 hours for a request with another method, path or body. Use a new key for a new request.
invalidRequest400The request is not valid. A field or parameter is missing or wrong; errors names each, with what is wrong.
invalidBody400The body is not readable. The body is not JSON, or a field has the wrong type.
invalidCursor400The cursor is not valid. Pass nextCursor exactly as a list returned it, with the same filters.
invalidUpdatedSince400updatedSince is not a moment. updatedSince is an ISO 8601 moment such as 2026-10-09T08:00:00Z.
invalidSort400Unknown sort. sort is changed (oldest change first, the default) or -created (newest first).
invalidIdempotencyKey400Idempotency-Key is not valid. An Idempotency-Key is 1 to 255 visible ASCII characters; a UUID is a good one.
invalid400An attendee's details are not right. errors names which attendee (from 0) and which field: firstName, lastName, email, company, jobTitle or a question id, with what is wrong (required, tooLong, notEmail, notOption).
soldOut400Sold out. The ticket type has no places left; ticketTypeId names it. Sent as 400 since v1 began, kept so for flows that branch on it.
unknownTicket400No such ticket type. ticketTypeId is not a ticket type of this event.
empty400Nobody to register. Send at least one attendee.
tooMany400Too many at once. At most 50 attendees in one request; send more requests.
registrationRefused400The registration was refused. Another reason the order was refused; reason says which, such as addOnSoldOut or namesLaterNotOffered.
eventType400Not an event type. event is one of the webhook event types (GET /webhooks/event-types).
webhookUrl400Not an address. url is an absolute https address without user name or fragment, at most 2,000 characters.
webhookHttps400Not https. url must be https.
webhookPrivate400Not a public address. url points at a private, loopback or link-local address, which AttendBeacon never calls.
tooManyHooks400Too many subscriptions. A workspace has at most 200 automation subscriptions. Switch off flows or Zaps it no longer needs.
tooManyEndpoints400Too many webhook endpoints. A workspace has at most 20 webhook endpoints. Remove one it no longer needs.
webhooksUnavailable503Webhooks are not available here. This deployment keeps no signing secrets, so endpoints cannot be added or given a new secret.
demoWorkspace403The demonstration is read-only. The demonstration workspace cannot be changed through the API.
rateLimited429Too many requests. The key made more than its calls a minute. Retry-After says when to try again; RateLimit says what is left.
serverError500Something went wrong here. An error on AttendBeacon's side. Retry with the same Idempotency-Key; traceId helps support find it.

Les gérer

const response = await fetch(url, { headers });
if (!response.ok) {
  const problem = await response.json();
  switch (problem.code) {
    case "rateLimited":
      await new Promise((resolve) => setTimeout(resolve, Number(response.headers.get("Retry-After")) * 1000));
      break; // and try again
    case "moduleOff":
      console.warn(`Skipping: ${problem.module} is switched off for this event.`);
      break;
    default:
      throw new Error(`${problem.code}: ${problem.detail} (trace ${problem.traceId})`);
  }
}

Les guides et ce site sont dans votre langue. Les descriptions propres à la référence de l’API restent en anglais, la langue de l’API elle-même.