Errors and retries

The errors

A fourth, CeejaySignatureError, belongs to the two signature checks. It is on Verifying signatures.

import { CeejayConnectionError, CeejayError } from '@communitystudios/ceejay'

try {
  await ceejay.economy.deduct({ discordId: '409876543210987654', amount: 100 })
} catch (error) {
  if (error instanceof CeejayError) {
    // CEEJAY answered, and refused or failed.
    console.log(error.status, error.code, error.message, error.requestId)
    console.log(error.body) // the whole answer, for the extra fields some refusals carry
  } else if (error instanceof CeejayConnectionError) {
    // No answer came back. A write may or may not have been applied.
    console.log(error.message, error.timedOut)
  } else {
    throw error
  }
}

The fields of a CeejayError:

Check the code, not the status or the message. The message text can change. A code does not: the list of codes is closed for version 1 of the API, and a code is never renamed or removed. Two errors of the same kind can carry different statuses, for a reason given under Statuses, so the status alone does not identify which rule failed.

Your key is never part of an error, whatever a server puts in its response. The SDK redacts your key from the response before it reads the message, the code or the body. The cause of a CeejayConnectionError is a plain copy of what the fetch threw: its name, its message and its code, and no other properties.

Errors every request can raise

These are the same for every request. The first six come before a request reaches its own checks, in this order.

A key that is missing, or does not start with ceejay_sk_, never leaves your server: the SDK throws a TypeError when the client is created.

The rate limit is checked before the permission. A key that is over its limit gets 429 from every request, also from one it has no permission for, and that request still counts. So a 429 does not tell you the key is permitted to make the call.

Two responses are generated before CEEJAY's own code runs, and carry no code and no requestId: a body larger than 1 MB (413, with the text Body exceeded 1mb limit), and a body that is not JSON. The SDK always sends JSON, so the second cannot happen through it. The SDK gives the first the code body_too_large, as it gives it to the 413 of ceejay.players.setFields and ceejay.players.logEvents for a body over 512 KB.

The rate limit

A key has a rate limit in requests per minute: 60 unless the key was given a different limit, and 600 at most. ceejay.community.get reports it as key.rateLimitPerMinute.

Every response to a request made with a known key carries three headers, on success and on error:

A 401 carries none of them: no key is known, so there is no limit to report.

The SDK does not expose these three headers to your code. It reads what it needs from a 429: the wait, which is on the error as retryAfter. To see how much of its rate limit a key has left, call ceejay.community.get for its limit and count your own requests.

Statuses

Four errors return 400 for backward compatibility, although the status for a business rule is 409: quest_not_active, quest_already_completed and quest_limit_reached on quests.complete, and insufficient_balance on economy.deduct. The other rules of a quest return 409. This is why you check the code.

Three more errors also keep their original status for backward compatibility: bot_unavailable and bot_timeout, with 502 or 504, when CEEJAY's bot could not finish a request, and discord_error, which passes Discord's own status through.

Codes

Every code of version 1 of the API. The page for each area lists the codes its own functions return, and what else is in error.body.

Idempotency keys

Every write takes one more option, idempotencyKey, but for the three writes of Connect, which take none: each of those is safe to retry as it is. The key is a string you choose, 1 to 128 characters, for one request. The SDK sends it in the body as idempotencyKey.

• When the same request is sent again with its key, nothing is repeated. The response is the original one, with duplicate: true.
• Each key identifies one request. Two requests for one event need two keys, for example match-9:coins and match-9:xp. The same key on another function, or with other values, is rejected with idempotency_key_reused.
• A key is stored only when its request was applied. A rejected request can be sent again with the same key once the cause is fixed.
• A key belongs to the API key that sent it, and is retained for 30 days.

Generate the key from something that identifies the request in your own system, such as an order ID or a match ID. A key generated from the time of the call is new on every attempt, and protects nothing.

The errors an idempotency key can produce:

idempotency_outcome_unknown applies to the three writes whose effect is outside CEEJAY and cannot be reversed or looked up: a posted message, a sent event and a reported quest task. After an attempt that got no response, CEEJAY retains the key and does not post, send or report a second time. The other writes are either applied in full or not at all, or are safe to apply twice, so a retry of them returns the original response.

What the SDK retries

After a 429, a 5xx or no response, the SDK waits and retries the request. It only does this when it is safe to retry:

• A read is retried.
• A write sent with idempotencyKey is retried.
• A write without a key is never retried. CEEJAY would apply it twice.

One more response is waited for and retried, for a write with a key: a 409 with the code idempotency_in_progress. It means the first request with that key is still running. The SDK can receive this when it retries after a dropped connection. Waiting returns the original response.

These are never retried, whatever the request:

• A status from 400 to 499 other than 429, with the one exception above. The request itself is invalid, and would be rejected again.
• A 409 with the code idempotency_outcome_unknown or idempotency_key_reused. Waiting changes neither.
• A 503 with the code idempotency_unavailable. This instance cannot store keys yet, and waiting does not change that.

How long it waits

Between two attempts the SDK waits as long as retryAfter in the response specifies. When the response has no retryAfter, it uses exponential backoff: the first wait is between 250 and 500 milliseconds, and each wait after that is twice as long, up to 8 seconds.

A wait of more than 60 seconds is not waited for. The error is thrown immediately, with retryAfter set, so your own code can decide.

Set both for every call when you create the client, or for one call in its last argument:

import { Ceejay } from '@communitystudios/ceejay'

const patient = new Ceejay({ apiKey: process.env.CEEJAY_API_KEY, maxRetries: 4, timeoutMs: 10_000 })

// One call that must answer quickly or not at all.
const member = await patient.members.get('409876543210987654', { maxRetries: 0, timeoutMs: 2_000 })

console.log(member.level)

A write that got no response

After a CeejayConnectionError, a write may or may not have been applied.

• With idempotencyKey, the SDK has already retried it with the same key. If it still fails, retry it later with the same key: it is applied once.
• Without a key, read before you write again. After a grant of XP that timed out, call ceejay.xp.getBalance and compare the total with what you expect.

A request that the rate limit rejected changed nothing, so it is always safe to retry. With a key, the SDK does that for you:

const grant = await ceejay.xp.grant(
  { discordId: '409876543210987654', amount: 250, reason: 'Won match 881' },
  { idempotencyKey: 'match-881:xp', maxRetries: 4 },
)

console.log(grant.xp, grant.duplicate)

Discord's own limit

roles.list, roles.grant, roles.revoke, channels.list and messages.send go through Discord, and one bot serves every community on an instance. When Discord rate-limits the bot, the call fails with status 429 and the code discord_rate_limited. retryAfter is Discord's wait in whole seconds, when Discord provided one. This is not your key's own rate limit: that is rate_limited.

Do not retry these in a tight loop: Discord can block the bot for a while, for every feature.

A member who has only just joined your server can take up to 15 seconds to be found. After a 404 with the code member_not_found for such a member, wait 15 seconds before you retry.

Stopping a call

Pass an AbortSignal as signal. When it is aborted the call stops and throws the reason of the signal, not one of the errors above.

const controller = new AbortController()
setTimeout(() => controller.abort(), 1_500)

const page = await ceejay.quests.list({ limit: 100 }, { signal: controller.signal })
console.log(page.total)

When you ask us for help

Send us the requestId of the error, and the time and the function you called. CEEJAY logs the URL path, method, status code and timestamp of every request made with a key it accepts.

Every request the SDK sends carries the header User-Agent: ceejay-sdk-typescript/0.1.0, with the version of the SDK you use.