Errors

Every failed request returns a non-2xx status and the same body: a message for a person, a fixed code for your program, and the ID of the request.

{
  "error": "discordId must be a valid Discord snowflake (17-20 digits)",
  "code": "bad_request",
  "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2",
  "field": "discordId"
}

Some codes add extra fields, such as required and granted, retryAfter, balance or feature. The table below names them, and each reference page lists the errors of its own request.

Act on the code, not on the status

The status follows one rule for everything new since version 1.0.0:

Four refusals do not follow that rule. They returned 400 before the codes existed, and they keep 400 for as long as version 1 exists, where a request that conflicts with a rule now returns 409:

So branch on code. A program that treats every 400 as "fix the request" and every 409 as "the request conflicts with a rule" gets these four wrong.

Three more statuses are named exceptions, because a caller could already read them: 502 for bot_unavailable and bot_timeout on Complete a quest task, 502 and 504 for the same two codes on Complete a shop delivery, and Discord's own status passed on with the code discord_error. The requests of the game loop are newer, and follow the rule: they return 503 and 504 for those two codes, and 409 for the quest rules and insufficient_balance that return 400 above. See the table below.

Every code

These are all the codes of version 1.0.0.

Codes of an organisation's key

An organisation's key covers several communities, and each request names one of them in the CEEJAY-Community header. These 2 codes are part of the same closed list, and only requests made with an organisation's key return them.

Codes of Connect

The requests of Connect add these codes. They are part of the same closed list, and they were added in version 1.1.0 of the API.

Codes of player data

The player requests add these codes. They are part of the same closed list, and they were added in version 1.1.0 of the API.

A batch that has problems is not an error: Set player fields and Log player events return 200 with a status for each player or event. The statuses and the problems are values of those responses, not codes of this list.

Three codes are in the list and no request returns them yet: field_name_taken, player_already_connected and banned. The API file names them under x-not-answered-yet on its ErrorCode schema.

Codes of the game loop

The requests of the game loop add these 14 codes. They are part of the same closed list, and they were added in version 1.1.0 of the API. The message of each is on the reference page of the request that returns it.

In the SDK, spend_on_hold and daily_spend_cap_reached are thrown as a CeejaySpendBlockedError: see The game loop, inside a game.

Statuses the game loop gives to codes that existed

Eighteen codes were in the list before the game loop. The requests of the loop return them with the status below, which follows the rule that a request that conflicts with a rule is 409. The older requests keep the status they have always had and never change it.

A refusal about a quest also includes message, text the game can show to the player.

Errors with extra fields

{
  "error": "Insufficient scopes",
  "code": "insufficient_scope",
  "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2",
  "required": ["economy:grant"],
  "granted": ["xp:grant", "xp:read"]
}

{
  "error": "Insufficient balance",
  "code": "insufficient_balance",
  "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2",
  "currentBalance": 120,
  "requested": 500,
  "balance": 120
}

{
  "error": "The proof of the player was not accepted",
  "code": "proof_rejected",
  "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2",
  "reason": "expired"
}

{
  "error": "Program is not active",
  "code": "program_not_active",
  "requestId": "req_5f0c2a9b7d3e41f8a6b0c1d2",
  "programStatus": "paused"
}

Key and limit errors

These come before any request runs, and every request can return them.

A 401 for a secret key carries X-Request-Id and no rate limit headers: no key is known, so there is no limit to report.

Errors every request of a game shares

The requests a game makes with its public key or a player session ("Connect: from the game" in the reference) do not take a secret key, so the table above does not apply to them. These come before any of them runs, in this order:

Every one of these responses includes X-Request-Id and the three rate limit headers, a 401 included: a game's request is counted against its IP address before its key is read.

The five Connect requests a server makes with a secret key share the key and limit errors above, with two differences. A Full Access key gets 403 with the code insufficient_scope, because players:connect is never part of *. And their 429 is about the game's own limit of 600 a minute, not the key's: see Rate limits.

The player requests (Get a player to Propose to the field map) share the key and limit errors too, and use the key's own limit. A Full Access key has players:read and players:write, and gets 403 with the code insufficient_scope on Disconnect a player (players:connect) and Delete a player (players:delete), and on a call to Set player fields or Log player events that sets underAge: true (players:connect).

Errors about an idempotency key

Every request that changes data accepts an idempotencyKey. Four responses are about the key itself:

Buy a shop item, which a game sends with a player session, is the one request of the game loop that takes a key, and it requires one. A key sent there belongs to the member, the game and the connection, and is retained for 30 days.

Responses that come before your key is read

CEEJAY returns these before any of its own code runs, so they are not JSON objects: they have no error, no code and no requestId, and they carry no X-Request-Id header.

Calls that go through Discord

Grant a role, Revoke a role and Send a message ask Discord to do the work, and pass its response on:

The two role requests first look the role up in your server's role list, which CEEJAY reads from Discord and caches for up to a minute. Then they check that it is not one of your community's bot master roles, which CEEJAY reads on every call. These responses come from those checks, before Discord is asked to change anything:

Validation rules worth knowing

• Send Content-Type: application/json with every JSON body. Without it the body is not read as JSON, and the response is a 400. With no content type, or text/plain, it is The request body must be a JSON object. With a form content type, which curl -d sends when you set none, it names a field as missing, as if you had left the field out. For example discordId must be a valid Discord snowflake (17-20 digits), even though the body contains a valid discordId.
• The body of a POST must be a JSON object. null, a string, a number and a list return 400 with The request body must be a JSON object. Complete a shop delivery and Complete a quest task return 400 with their own first message instead.
• Each field has one current name, such as discordId, playerId, reason and idempotencyKey. Every name a request accepted before is still accepted: each reference page lists the older names. When both names of one field are sent, the older one is used, and nothing is refused for sending both.
• discordId must be a string of 17–20 digits. A JSON number cannot represent all the digits: its last ones would change, so it could name a different member. It is refused with 400, like any other value that is not a string, and so is a roleId, a channelId or an ID in allowedRoleIds sent that way. On Complete a quest task a discordId that is not a string of 17 to 20 digits returns 202, not 400.
• Text is sent as a JSON string. reason on the XP and currency requests, content on Send a message, and taskKey and evidence on Complete a quest task return 400 for a number, a list or an object. On Complete a quest task an xHandle, wallet, github or twitch can also be a whole number, which is read as its digits. Any other value that is not a string returns 202.
• Text and JSON that CEEJAY stores cannot contain a null character (U+0000). It returns 400 with the name of the field, such as reason cannot contain a null character, and nothing is changed or sent. This covers reason, every idempotencyKey, proof on Complete a quest, the platform, ID and name on Link an account, data on Emit an event, status and category on List quests, evidence and the identifier a member is looked up by on Complete a quest task, and message on Complete a shop delivery.
• Text that CEEJAY stores as a key or inside JSON must be well-formed Unicode. Half of a surrogate pair, such as the JSON "\ud800" or an emoji cut in two, returns 400 in an idempotencyKey, in reason on Grant program XP and Deduct program XP, in proof on Complete a quest, in data on Emit an event, in evidence on Complete a quest task and in message on Complete a shop delivery.
• proof on Complete a quest and data on Emit an event can nest lists and objects up to 32 levels deep. A deeper value returns 400.
• amount must be a positive whole number, sent as a JSON number. XP grants cap at 100,000 per call, and so do program XP grants and deductions. Currency grants cap at 1,000,000. XP deductions and currency deductions cap at 2,147,483,647, the largest whole number the database stores. An amount above the cap returns 400.
• A questId and a programId are whole numbers from 1 to 2,147,483,647, sent as a JSON number or as a string of digits written without leading zeros. A fraction, a negative number or a larger one returns 400. So does such a purchase ID in a path.
• Balances, totals and other counts in a response are always JSON numbers, never text. CEEJAY's own IDs of quests, programs and purchases are numbers in every response.
• Deducting more currency than a member has returns 400 with their current balance. A balance never goes negative.
• Deducting XP below zero floors at zero rather than failing.
• A currency grant that would take a member over the community's balance cap credits only the amount that fits and reports that in the response. It is not an error.
• The requests that change a member's XP, currency, quests or linked accounts (Grant XP, Grant program XP, Grant currency, Complete a quest and Link an account) only write to a member of your server. An ID CEEJAY has no profile for is looked up in Discord first, and one that is not in your server returns 404 with the code member_not_found. A member who has only just joined can take up to 15 seconds to be found: wait 15 seconds before retrying. Complete a quest task makes the same check on a discordId, and returns 202 for one that is not in your server. When CEEJAY cannot confirm with Discord whether an ID is a member, the response is 503 with the code discord_unavailable and nothing is written. The requests that read a member behave as before.

Each reference page lists the errors its own request can send.