Theme
Handling errors
Failures are RFC 9457 problem documents, served as application/problem+json:
json
{
"type": "about:blank",
"title": "Validation failed",
"status": 400,
"code": "VALIDATION_FAILED",
"detail": "One or more fields are invalid.",
"errors": [
{ "path": "links.0.metadata.author_email", "message": "author_email is not a valid email address" }
],
"traceId": "Cw7-AggGliAEJiQ="
}| Field | Use it for |
|---|---|
code | Branching. Stable, machine-readable, part of the v1 contract. |
detail | Showing a human what went wrong. |
errors[] | Pointing at the offending field on validation failures. |
traceId | Quoting to us. It is how we find your request. |
type | Always about:blank. Carries no information — see below. |
title, status | Logs and dashboards. |
Branch on code, not status
status is coarser than code: three distinct problems share 403, and a missing campaign and a missing survey link are both 404 while meaning different things and wanting different handling.
type is no help either — it is always about:blank, RFC 9457's default for a problem carrying no semantics beyond its status code. It is not a link and not a discriminator. The documentation for each problem is on this site, linked from the table below.
Some responses are not problem documents
Authentication is rejected at the gateway, before the service runs, so these carry no code and no problem shape:
| Response | Body | Means |
|---|---|---|
401 | {"message":"Unauthorized"} | No Authorization header, or not a bearer token |
403 | {"message":"Forbidden"} | Key is malformed, unknown, revoked or expired |
One more 403 comes from the edge, before the gateway: a request body over 64 KB is refused with an HTML page that says "The request could not be satisfied". Nothing was processed. Split the request and send the parts.
So: a 403 whose body is JSON but not a problem document is an invalid credential. A 403 that is one is a valid key being refused for what it may do — see insufficient scope.
Codes
| Status | code | Meaning |
|---|---|---|
400 | VALIDATION_FAILED | A field is missing or malformed |
403 | INSUFFICIENT_SCOPE | Valid key, missing scope |
404 | CAMPAIGN_NOT_FOUND | No such campaign in this workspace |
404 | SURVEY_LINK_NOT_FOUND | Link consumed, expired, revoked, or never existed |
413 | BATCH_TOO_LARGE | More entries in one call than the endpoint allows |
429 | RATE_LIMIT_EXCEEDED | Budget spent for this minute |
500 | — | Our fault |
What to retry
| Retry? | |
|---|---|
429 | Yes, after Retry-After. |
5xx | Yes, with backoff. |
400, 403, 404, 413 | No. Fix the request. |
401 | No. The credential is missing or wrong. |
Creating links is not idempotent
A retry that reaches us twice mints two sets of links, and there is no idempotency key. Honour Retry-After rather than retrying on your own schedule.
reference will not rescue you here: it comes back on the create response and is not stored, so it cannot be looked up afterwards. See retrying a chunk.
Sending conversation metadata is the exception: a row resent with the same conversation_id and leg_id replaces the earlier one, so a whole batch can be retried. See Retrying is safe.
Partial failures are not errors
Batch creates answer 207 Multi-Status when some entries succeed and others fail. That is a success response with a mixed body, not a failure — read items[] per entry. See Creating links in bulk. Conversation metadata does the same, listing only the rejected rows in errors[]. See The response.
