Skip to content

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="
}
FieldUse it for
codeBranching. Stable, machine-readable, part of the v1 contract.
detailShowing a human what went wrong.
errors[]Pointing at the offending field on validation failures.
traceIdQuoting to us. It is how we find your request.
typeAlways about:blank. Carries no information — see below.
title, statusLogs 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:

ResponseBodyMeans
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 ​

StatuscodeMeaning
400VALIDATION_FAILEDA field is missing or malformed
403INSUFFICIENT_SCOPEValid key, missing scope
404CAMPAIGN_NOT_FOUNDNo such campaign in this workspace
404SURVEY_LINK_NOT_FOUNDLink consumed, expired, revoked, or never existed
413BATCH_TOO_LARGEMore entries in one call than the endpoint allows
429RATE_LIMIT_EXCEEDEDBudget spent for this minute
500—Our fault

What to retry ​

Retry?
429Yes, after Retry-After.
5xxYes, with backoff.
400, 403, 404, 413No. Fix the request.
401No. 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.

Zefi API v1