Error reference

Every refusal from a surface of this API is an RFC 9457 problem document with a stable code, a detail written for a person, and a correlation_id that joins your response to this deployment's audit trail.

That holds under /v1/ for a request that never reaches a surface too — an address this API does not route, or a method a route does not take. Those answer not_found and http_error respectively, with a correlation_id and without rate-limit headers, because no limiter saw them. Outside /v1/ you are not talking to this API, and an address there answers with an ordinary web page, not a problem document.

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "code": "token_expired",
  "detail": "The token expired at … which is 3600 seconds ago; this deployment's clock reads … Tolerance is 60s either way — if that offset looks like your clock rather than your code, check NTP on the signing host.",
  "correlation_id": "01a04a82-068b-7298-b042-be7b1bbda8dc",
  "errors": [{ "pointer": "/claims/exp", "code": "expired" }]
}

Branch on code, never on detail. The code is the contract and is locale-invariant; the sentence is written for a reader and may be reworded.

errors[] names the member at fault. Each entry carries a RFC 6901 pointer into what you sent — /participants/2/subject/user_id, not "invalid input" — a code from the vocabulary below, and usually a message written for a person. Branch on pointer and code; the message may be reworded. Every bad entry is reported, not only the first.

Some refusals carry extension members that make them actionable: a join window's window_opens_at, a provisioning failure's cause. They are listed with the code below. RFC 9457 section 3.2 allows this, and a number the deployment already knows should never be something you derive from prose.

A code narrows the problem. Where one code covers more than one fault — token_malformed covers six, download_reference_invalid four — its row names them all, and the detail says which one you met. download_reference_invalid is the exception: its four causes are merged so that an anonymous caller cannot probe which references exist, and its detail does not distinguish them.

Two pairs of codes describe the same remedy from different sides, and their rows say so: token_missing and no_valid_principal both mean "send a credential", and token_tenant_mismatch and tenant_mismatch are the same disagreement seen by an application and by a person.

The credential is not usable

The credential is valid, the request is not permitted

The request is malformed

The resource is not in a state that allows this

Registering or revoking a key

You are going too fast

The address or the method is wrong

This deployment could not do it

Redeeming an artefact download reference

errors[].code — the field-level vocabulary

When a specific member of your request is at fault, errors[] names it with an RFC 6901 JSON Pointer and one of these. They are deliberately general: the pointer says where; this says what kind. Pairing a specific location with a general kind is what makes a validation error machine-readable without inventing a code per field.

Two of them — target_not_permitted and event_unknown — are spelled the same as a top-level code. Position tells you which vocabulary you are reading: a string inside an errors[] entry is from this table, and a string at the top level of the document is from the tables above.

An errors[] entry usually carries a third member, message, written for a person. Branch on pointer and code; the message may be reworded.

Headers on a refusal

X-Correlation-Id carries the same value as the body's correlation_id, on every response. Send one of your own and it is echoed back, so a trace joins at both ends; send none and this deployment generates one. It is the value to quote when you report a fault.

Allow accompanies a 405 and names the methods that address does take.

Retry-After accompanies a 429. Idempotency-Replayed: true accompanies the stored answer to a repeated Idempotency-Key.

Rate-limit headers

Two limiters sit in front of these surfaces, and the headers report whichever one the response passed through. Reading the wrong one is the mistake to avoid.

The per-application limiter is the one you budget against. Its ceiling is rate_limit_per_minute from GET /v1/integrator/discovery. It runs after your credential is verified, and it sets X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset on every response it sees, not only on the 429 — so you can back off before you are refused rather than after.

A per-address limiter runs in front of the credential check, on every surface that verifies one. It bounds how many credentials an address may FAIL to verify in a minute. A credential that verifies is not charged to it, so it sits beside your application budget rather than under it: an application making its published rate_limit_per_minute requests from one address never meets it.

Two things follow, and the second is the one to design for:

• A run of refusals is bounded. Once an address is over, every request from it is 429 rate_limited with a Retry-After, and the detail says the limit counts failed verifications.
• While it is over, a credential that WOULD verify is refused too — the limiter runs before the check, so it cannot know. If your application shares an egress address with something that is failing to authenticate, you will feel it. Fix the failing credential rather than retrying through it.

Its ceiling is separate from the published one and is not in discovery. GET /v1/integrator/discovery and GET /v1/applications/me additionally carry a per-address limiter that reports itself in X-RateLimit-Limit and X-RateLimit-Remaining, which is why those two surfaces show a lower number than your application budget.

What follows from that ordering:

• On a response to a request that carried a verified credential, the headers are your application's budget.
• Where they appear on any other response — a 401, or GET /v1/integrator/discovery, which needs no credential — they report the per-address limiter, and the number will be lower than rate_limit_per_minute. Most refusals carry no rate-limit headers at all, so their absence tells you nothing.
• GET /v1/applications/me passes through both, and reports the per-address number, because the outer limiter writes last.
• A request that never reached a surface at all carries no rate-limit headers.

So: budget against rate_limit_per_minute from discovery, and treat the headers as your own budget only on responses to authenticated requests.

X-RateLimit-Reset is an absolute unix timestamp; Retry-After, present on the 429, is a duration in seconds.

What a refusal leaves behind

No work. Every mutation runs in one transaction, so a refused request leaves no half-created meeting and no invitation sent for a meeting that does not exist.

One thing a refused request does spend is rate-limit budget: it is taken before the operation starts, so a run of refusals counts against you exactly as a run of successes would. X-RateLimit-Remaining falls on a 401.

The one thing to know: a request that failed spends no idempotency key. Fix the body and send it again with the same key.