Skip to Content

Errors

Every error is RFC 9457 problem JSON with a stable code. The full list of codes and their HTTP statuses.

Every error response has the content type application/problem+json and this shape:

{
  "type": "https://whocoming.com/docs/errors#validation_failed",
  "title": "The request is not valid",
  "status": 400,
  "code": "validation_failed",
  "detail": "One field is not valid. See errors for details.",
  "request_id": "req_4k9x2m7q1c8v5b3n6z0a",
  "errors": [{ "field": "starts_at", "message": "Required", "code": "required" }]
}
FieldMeaning
codeBranch on this. A stable string that never changes meaning. New codes may be added.
statusThe HTTP status, repeated.
titleA short summary of the code.
detailWhat went wrong this time, in plain words. It may change; do not parse it.
typeA link to this page, at the code's row.
request_idQuote it when you contact support. Every response, success or not, also sends it as the X-Request-Id header.
errorsOnly for field problems: one entry per field.

Field errors

errors[].field is a dotted path into your request, such as email, answers.deck or fields.0.key. errors[].code is one of:

required, invalid_type, invalid_format, invalid_value, too_small, too_big, unrecognized_keys, invalid.

Error codes

CodeStatusWhat it means
validation_failed400A field is missing or not valid. errors[] lists each field by its dotted path, such as email or answers.deck.
unauthorized401No API key, a malformed Authorization header, or a key that is unknown or revoked.
insufficient_scope403The key works but lacks the scope this endpoint needs.
not_found404The path does not exist.
event_not_found404No event with that ID in this organization and mode. A test key never sees live events, and the public API does not serve private events.
series_not_found404No series with that ID in this organization and mode.
rsvp_not_found404No RSVP with that ID, or the manage token is not valid.
webhook_endpoint_not_found404No webhook endpoint with that ID in this mode.
delivery_not_found404No webhook delivery with that ID in this mode.
capacity_reached409The event is full and has no waitlist.
already_registered409This email already has a going or waitlisted RSVP for the event. On the public API the guest is emailed their manage link again.
event_not_open409The event is not taking RSVPs, for example because it is still a draft.
event_cancelled409The event was cancelled.
event_ended409The event has ended.
too_many_guests422guests is higher than the event's max_guests.
plan_limit403Your plan's limit for this resource is reached (API keys, webhook endpoints, custom fields or active series). RSVPs never fail with this code.
rate_limited429Too many requests. Wait for the number of seconds in Retry-After.
idempotency_conflict409This Idempotency-Key was already used with a different request body (for example another guest's email), or the first request is still running. Nothing was created.
origin_not_allowed403The organization limits which websites may send RSVPs, and this page's origin is not on the list.
bot_check_failed403The Turnstile token is missing or did not verify.
mode_mismatch403The request mixes live and test data.
sandbox_limit429Too many sandboxes from this IP address. Try again later.
rsvp_not_going409Only an RSVP with status going can be checked in. Cancelled, not going and waitlisted RSVPs answer 409. Undoing a check-in works whatever the status.
internal_error500Something went wrong on our side. Retry with backoff and quote the request_id.

Handling errors

  • 4xx means the request needs to change. Retrying the same request gets the same answer, except 429.
  • 429: wait for the number of seconds in the Retry-After header, then retry.
  • 5xx: retry with exponential backoff. Send an Idempotency-Key on creating requests so a retry cannot create a duplicate.
const res = await fetch(url, init);
if (!res.ok) {
  const problem = await res.json();
  switch (problem.code) {
    case "already_registered":
      // The guest is already on the list. Show them a friendly message.
      break;
    case "capacity_reached":
      // The event is full and has no waitlist.
      break;
    default:
      throw new Error(`${problem.code}: ${problem.detail} (${problem.request_id})`);
  }
}

@whocoming/sdk throws a typed WhoComingError with code, status and requestId.

On this page