Errors

Errors come back as JSON with the HTTP status you would expect and a machine- readable code you can switch on. Branch on code, not on the human-readable message — messages are free to change, codes are part of the contract. There is one shape for every deliberate error and a second, slightly different one for request-validation failures.

The error body

{
  "statusCode": 404,
  "code": "TOURNAMENT_NOT_FOUND",
  "message": "TOURNAMENT_NOT_FOUND"
}

Every code

Anything in the 5xx range is a fault on SETTO's side. Retry with exponential backoff and jitter; if it persists, the payload you were asking for is probably not the problem.

Validation errors

A 400 from the global validation layer is the one response that does not use the uniform shape: its message is an array of strings, one per failed rule.

{
  "statusCode": 400,
  "message": [
    "must be a valid enum value,club,club.courts,divisions,divisions.rounds,sponsors,circuit,circuitCategory,rankedTiebreakRules"
  ],
  "error": "Bad Request"
}

Handle it defensively:

const body = await res.json();
const message = Array.isArray(body.message)
  ? body.message.join('; ')
  : body.message;

The usual causes, in order of frequency:

1. A populate value that is not on that endpoint's allow-list — the lists are in Populate, and the error message enumerates the legal values for you.
2. limit outside 1..100, or offset below 0.
3. A status or sport value that is not one of the enum members.
4. A division filter that is not a UUID v4.

A malformed path id is the other 400

400 covers two different shapes. The array-of-strings body above comes from the query-parameter layer. A path identifier that is not a v4 UUID — say /v1/external/tournaments/not-a-uuid — is rejected earlier, and answers in the API's uniform shape instead:

{
  "statusCode": 400,
  "code": "INVALID_ID",
  "message": "INVALID_ID"
}

The distinction that matters: a malformed idx is a 400, never a 404. Only a well-formed id that this token cannot reach gets the 404 below. So INVALID_ID always means your string is wrong, not the resource is missing.

404 hides more than it says

A 404 means this token cannot reach such a resource. It does not distinguish between:

• an idx that exists nowhere in SETTO;
• an idx that belongs to an organization this token does not reach;
• an idx of a tournament the token's owner does not manage — or no longer manages: a personal token's reach is worked out again on every request;
• an idx that belongs to a personal tournament, which only its owner's personal token reaches.

That is deliberate: the API never confirms the existence of data your token cannot read, so ids cannot be probed. Practically, if you are certain the tournament exists, check that you are using a token that reaches it: the organization token of the organization that owns it, or the personal token of someone who manages it.

Refused writes

A write that is refused wrote nothing, and its body adds details: one entry per game, team or player that blocked it, each { code, … } with the keys that apply (gameIdx, teamIdx, index, field, limit, current, step, reason, …). Each operation's page in the API reference lists the codes it can answer. The ones that shape a client's logic:

Every other refusal of a write (a name taken, a full category, a team that already has games, a schedule conflict, …) is a state the organizer decides on: show them the details rather than retrying.

What to do on each status

const MAX_RETRIES = 3;

async function settoFetch(path, { token, attempt = 0, ...init } = {}) {
  const res = await fetch(
    `https://api.setto.io/v1${path}`,
    {
      ...init,
      headers: { ...init.headers, Authorization: `Bearer ${token}` },
    },
  );

  if (res.ok) return res.json();

  const body = await res.json().catch(() => ({}));

  const canRetry = attempt < MAX_RETRIES;
  const retry = async (waitMs) => {
    await new Promise((r) => setTimeout(r, waitMs));
    return settoFetch(path, { ...init, token, attempt: attempt + 1 });
  };

  switch (res.status) {
    case 401:
      // MISSING_API_TOKEN | INVALID_API_TOKEN | EXPIRED_API_TOKEN
      throw new Error(`SETTO credential problem: ${body.code}`);
    case 403:
      throw new Error('SETTO token lacks the required scope');
    case 404:
      return null; // caller decides whether a miss is fatal
    case 429:
      // Honour Retry-After, but give up rather than loop forever: a token that
      // is over budget every time would otherwise spin here indefinitely.
      if (!canRetry) throw new Error('SETTO API: still rate limited');
      return retry(Number(res.headers.get('Retry-After') ?? 1) * 1000);
    default:
      // 5xx only, with exponential backoff and jitter so a fleet of clients
      // does not come back in lockstep.
      if (res.status >= 500 && canRetry) {
        return retry(2 ** attempt * 500 + Math.random() * 250);
      }
      throw new Error(`SETTO API ${res.status}: ${JSON.stringify(body)}`);
  }
}

Retry 429 and 5xx, and bound it — three attempts here. Never retry 400, 401, 403 or 404: the same request will fail the same way, and a retry loop on 401 just burns your rate limit.

Related

• Authentication — the full 401 vs 403 breakdown.
• Rate limits — the headers that let you avoid 429 altogether.