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" }]
}| Field | Meaning |
|---|---|
code | Branch on this. A stable string that never changes meaning. New codes may be added. |
status | The HTTP status, repeated. |
title | A short summary of the code. |
detail | What went wrong this time, in plain words. It may change; do not parse it. |
type | A link to this page, at the code's row. |
request_id | Quote it when you contact support. Every response, success or not, also sends it as the X-Request-Id header. |
errors | Only 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
| Code | Status | What it means |
|---|---|---|
validation_failed | 400 | A field is missing or not valid. errors[] lists each field by its dotted path, such as email or answers.deck. |
unauthorized | 401 | No API key, a malformed Authorization header, or a key that is unknown or revoked. |
insufficient_scope | 403 | The key works but lacks the scope this endpoint needs. |
not_found | 404 | The path does not exist. |
event_not_found | 404 | No 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_found | 404 | No series with that ID in this organization and mode. |
rsvp_not_found | 404 | No RSVP with that ID, or the manage token is not valid. |
webhook_endpoint_not_found | 404 | No webhook endpoint with that ID in this mode. |
delivery_not_found | 404 | No webhook delivery with that ID in this mode. |
capacity_reached | 409 | The event is full and has no waitlist. |
already_registered | 409 | This 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_open | 409 | The event is not taking RSVPs, for example because it is still a draft. |
event_cancelled | 409 | The event was cancelled. |
event_ended | 409 | The event has ended. |
too_many_guests | 422 | guests is higher than the event's max_guests. |
plan_limit | 403 | Your plan's limit for this resource is reached (API keys, webhook endpoints, custom fields or active series). RSVPs never fail with this code. |
rate_limited | 429 | Too many requests. Wait for the number of seconds in Retry-After. |
idempotency_conflict | 409 | This 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_allowed | 403 | The organization limits which websites may send RSVPs, and this page's origin is not on the list. |
bot_check_failed | 403 | The Turnstile token is missing or did not verify. |
mode_mismatch | 403 | The request mixes live and test data. |
sandbox_limit | 429 | Too many sandboxes from this IP address. Try again later. |
rsvp_not_going | 409 | Only 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_error | 500 | Something 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-Afterheader, then retry. - 5xx: retry with exponential backoff. Send an
Idempotency-Keyon 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.