Errors

Every failure returns the same body, as application/problem+json. It is a RFC 9457 problem document with three fields added: code, errors and traceId.

{
  "title": "Not Found",
  "status": 404,
  "detail": "Event 'order_placed' was not found.",
  "instance": "/v1/events",
  "code": "event.not_found",
  "errors": [
    {
      "code": "event.not_found",
      "message": "Event 'order_placed' was not found.",
      "meta": null
    }
  ],
  "traceId": "00-4f3c1a9e7b2d48c0a1e5f60b93d2c714-9a1c7f0e2b6d4358-01"
}

When a request breaks several rules at once, all of them are in errors and the first is copied into code and detail.

Branch on code, not on the message

code is stable. detail and every message are prose and can be reworded at any time.

if (!response.ok) {
  const problem = await response.json()

  switch (problem.code) {
    case "points.insufficient_balance":
      return showBalanceTooLow()
    case "marketplace_item.out_of_stock":
      return showSoldOut()
    case "points.concurrent_update":
      return retryOnce()
    default:
      throw new Error(`${problem.code}: ${problem.detail} (trace ${problem.traceId})`)
  }
}

Statuses

400, 401, 402, 403, 404, 409, 429 and 500 are the only ones you will see.

A 400 names the field it refused, so you do not need a table of every validation code: read errors and fix the request. A field the request could not be read at all without comes back as validation. plus that field, and validation.request when nothing can be named.

{
  "title": "Bad Request",
  "status": 400,
  "detail": "The request is invalid.",
  "instance": "/v1/players",
  "code": "validation.player_id",
  "errors": [
    {
      "code": "validation.player_id",
      "message": "The PlayerId field is required.",
      "meta": null
    }
  ],
  "traceId": "00-44583bf7ff0c47e3c30eb3277bb1eb81-547d059bf239562f-00"
}

detail on these is always the same sentence, so read errors.

A 500 is always server.unexpected, carries no stack trace, and may be worth one retry.

On any endpoint

How many requests at once

There is no limit on requests per second. There is a limit on how many you have in flight at the same time: 16, with 8 more allowed to wait their turn. Anything beyond that is refused straight away with 429, tenant.too_many_concurrent_requests and a Retry-After header in seconds.

The limit belongs to your organization, not to a key or an environment, so a backfill running against Sandbox takes slots from Live.

This is what makes batching worth it. One request carrying 1,000 events takes one slot; a thousand requests carrying one event each need a thousand.

Sending events

POST /v1/events answers 200 even when items were refused, and each item carries its own code. See Sending events.

The whole call is refused with event_batch.empty, event_batch.too_large (over 1,000 items), or event_batch.concurrent_update (409, nothing was written, send it again).

Attributes

A set is all or nothing: one bad key writes none of them.

Missions and streaks

The shop

Points

Limits

Retrying

• 409 with concurrent_update in the code. Nothing was written. Send the same request again.
• 429. Nothing was written. Wait for Retry-After and send it again. Getting them steadily means sending fewer at once, not retrying faster.
• 401, 400, 403 and 404. Nothing will change on its own. Fix the request, or fix the setup in the dashboard.
• 500. Retry with backoff, and send an idempotency key where the endpoint takes one.