Errors#

When an API call fails, the status code tells you what kind of problem it is, and most errors also carry a JSON body with a readable message. This page lists the errors of every public endpoint, in the order the checks run.

These are errors of the API call itself. What happens when your target URL fails later, when the trigger fires, is described in How triggers fire.

Error format#

Most errors come with Content-Type: application/json and a body like this:

{
  "_tag": "BadRequest",
  "message": "Invalid URL: example.com"
}

• _tag always matches the status code, so you can branch on either.
• message is meant for people and often contains the value that was rejected, such as the URL or the tag. Log it rather than parse it.
• Only the first failed check is reported. After you fix it, the same request can fail on a later check.

Errors without a JSON body#

Some errors are returned before the endpoint's own checks run, so they don't have the JSON body:

Handling errors#

• Don't resend a request that got a 4xx without changing it first. A 402 lasts until your quota resets or your limit changes.
• If you retry a /cancel after a timeout, a 404 or 410 can mean the first attempt already worked. See Cancelling again.

/schedule#

Applies to creating triggers and to editing them. The checks run in the order of this table, and the first one that fails is returned:

What the order means:

• An invalid URL or tag is reported even when the API key is wrong (400). An invalid ttr-scheduled-atheader with a wrong key gets 401.
• Tags are checked one at a time in the order you list them, length first, then characters. So Bad,<a 51-character tag> gets Invalid tag for Bad.
• Calls rejected with 400, 401 or 402 don't use quota. A call that passes the quota check uses one unit, even if it then fails with 404 or 410.
• 404 and 410 only come from edits by ttr-trigger-idheader. With a date or now, if you also send ttr-custom-keyheader and it belongs to a registered, skipped or retrying one-shot trigger, that trigger is edited and the ID isn't checked. With cron(...), the ID is always checked. See Sending both identifiers.

/cancel#

Only DELETE is accepted. A successful cancel returns 204 with an empty body. The checks run in the order of this table:

/declare#

The checks run in the order of this table:

/bulk#

/bulk returns the same errors as /declare, with these differences:

Cancel targets that match nothing, or only triggers that can't be cancelled anymore, are skipped without an error, so /bulk never returns 404 or 410. It never returns 402 either. See Bulk apply.

/tag-policies#

The checks run in the order of this table:

The 400 validation messages, in the order they are checked:

• Invalid tag (only a-z 0-9 _ - allowed, max 50 chars)
• At least one of throughput, concurrency, timeout, or retry strategy must be specified (POST only)
• requestTimeoutSeconds must be between 1 and 3600
• maxConcurrent must be ≥ 1
• At most 8 throughput windows per policy
• Throughput rate for '<window>' must be a finite number ≥ 0
• Effective window for '<window>' at rate <rate> exceeds the 30-day maximum, followed by (rates below 1 stretch the window by 1/rate) when the rate is above 0 and below 1
• retryMaxAttempts must be ≥ 1 (or null for unlimited)
• retryInitialDelaySeconds is required (≥0) when retryStrategy is 'fixed' or 'exponential'
• retryMaxDelaySeconds must be ≥ 0
• retryInitialDelaySeconds must be ≤ 86400 (1 day)
• retryMaxDelaySeconds must be ≤ 86400 (1 day)

On PUT, the retry messages are checked against the policy as it would be after the update, so changing retryStrategy alone can fail if the stored policy has no initial delay. See Validation messages for the rules behind each message.