Countdown Timer API error codes

The error response

An error body has no data key at all, which is why testing response.ok is more reliable than checking whether a field you expected is present.

HTTP/1.1 400 Bad Request
X-Request-Id: 7b82b7f7-4d13-497b-9f20-58d46fd7a510

{
  "error": {
    "code": "validation_error",
    "message": "deadline_at must be an ISO 8601 date-time with Z or a numeric UTC offset"
  },
  "request_id": "7b82b7f7-4d13-497b-9f20-58d46fd7a510"
}

The request_id appears twice on purpose: in the body for your logs, and in the X-Request-Id header so it is available even when a response body is not captured. Quote it when you contact support — it turns a vague report into a single lookup.

Every code

Authentication and access

Request problems

Conflicts

Limits

Server

The two 429s are not the same

Both are HTTP 429, and treating them identically is the most consequential error-handling mistake available here. A client that backs off and retries on quota_exhausted will retry all month.

{
  "error": {
    "code": "quota_exhausted",
    "message": "The monthly new timer allowance for this plan is spent",
    "details": {
      "metric": "new_timers",
      "limit": 1000,
      "used": 1000,
      "resets_at": "2030-02-01T00:00:00.000Z"
    }
  },
  "request_id": "7b82b7f7-4d13-497b-9f20-58d46fd7a510"
}

What is worth retrying

// Branch on code, never on message. Messages are written for
// humans and may be reworded; codes are part of the contract.
try {
  await createTimer(body, idempotencyKey);
} catch (error) {
  switch (error.code) {
    case "quota_exhausted":
      // Not transient — the allowance resets with the billing cycle.
      await notifyOps("Countdown timer allowance exhausted");
      return fallbackWithoutCountdown();

    case "rate_limited":
      // Transient. Retry-After says how long to wait.
      await sleep(error.retryAfter * 1000);
      return retry();

    case "revision_conflict":
      // Someone wrote first. Re-read and reapply.
      return retryWithFreshRevision();

    case "validation_error":
    case "missing_field":
    case "invalid_timezone":
      // Our bug. Retrying will fail identically.
      logger.error("Bad request to countdown API", {
        code: error.code,
        message: error.message,
        requestId: error.requestId,
      });
      throw error;

    default:
      throw error;
  }
}

The four that catch first integrations

1. 01

   invalid_api_key on a key you just created

   Environment mismatch. A cs_test_ key against a Production timer, or the reverse. Check the prefix before anything else.

2. 02

   missing_field on a create that looks complete

   The Idempotency-Key header, not a body field. It is required on POST /timers.

3. 03

   validation_error on deadline_at

   The timestamp has no Z and no numeric offset. 2030-01-01T14:00:00 does not identify an instant.

4. 04

   not_found on a timer you can see in the dashboard

   Same environment problem as the first, wearing a different hat. The timer exists — just not for the key you are holding.

Investigating an error you cannot reproduce

GET /usage/requests returns your own request log, filterable by status, route, key, and request ID. It shows what we received and what we answered, which resolves most “it works locally” reports without anyone opening a ticket.

If you do need support, send the request_id. It is the fastest path to an answer, and without it the first reply will only ask for it.