API reference

Errors

Errors use ordinary HTTP status codes and one JSON shape. The code is stable; the message is for a person.

Error codes

Status	Code	When
400	`invalid_json`	The body is not valid JSON.
401	`unauthorized`	The API key is missing, malformed or revoked.
403	`environment_not_enabled`	A live key was used before live access is enabled for the organization.
404	`not_found`	No such object in this organization and environment.
409	`idempotency_conflict`	This Idempotency-Key was already used with a different body.
422	`validation_failed`	A required field is missing or malformed. The response names the field.
422	`touchpoint_not_found`	The organization has no touchpoint with that slug, or it is turned off.
422	`member_not_found`	No active member matches the member you named.
422	`member_ambiguous`	More than one member has that email address. Send the member's id or external_id instead.
429	`rate_limited`	Too many requests. Wait for the time in Retry-After and send again with the same Idempotency-Key.
500	`internal_error`	Something failed on our side. Safe to retry with the same Idempotency-Key.

What to retry

Response	Retry?
`429`, `5xx`, or no response	Yes, with the same Idempotency-Key
Any other `4xx`	No. Fix the request first

422 · validation_failed

{
  "error": {
    "code": "validation_failed",
    "message": "A required field is missing or malformed. The response names the field.",
    "param": "recipient.phone"
  }
}

422 · touchpoint_not_found

{
  "error": {
    "code": "touchpoint_not_found",
    "message": "The organization has no touchpoint with that slug, or it is turned off.",
    "param": "touchpoint"
  }
}