Errors - Tera Contracted Supplier API

Errors use the runtime envelope. Tera never echoes submitted payloads, names, emails, telephone numbers, evidence objects, HMAC values, or fingerprints.

{
  "error": {
    "code": "validation_error",
    "message": "Request failed schema validation.",
    "details": [
      { "path": "telephone", "message": "A UK-contactable telephone number is required" }
    ]
  }
}

Every response includes X-Request-Id. That header is the only correlation identifier. The JSON body does not include request_id.

Statuses

HTTP	Code	When
200	—	Identical create replay, GET, or idempotent operation replay
202	—	New create persist, or promotion accepted for processing
400	`bad_request`	Malformed JSON, invalid content type, or missing required query
401	`unauthorized`	Missing or invalid credential
403	`forbidden`	Valid credential but insufficient scope or unauthorised level. No row is created.
404	`not_found`	Unknown or cross-tenant `submission_id` / `external_reference`. Same body in both cases.
409	`external_reference_conflict`	Same create `external_reference` with a different body. Not a commercial duplicate.
409	`revision_conflict`	Contact correction used a stale `expected_revision`.
409	`idempotency_conflict`	The same `operation_idempotency_key` was reused with a different body.
409	`concurrent_promotion`	Another promotion is already in progress or linked.
413	`payload_too_large`	Body exceeds the 64 KiB limit. Nothing is persisted.
422	`validation_error`	JSON parsed but failed the level schema (unknown field, range, or evidence).
429	`rate_limited`	Identity, IP, or failed-auth limiter. See `Retry-After`.
503	`service_unavailable`	Temporary upstream or platform unavailability. Retry with backoff.

Commercial duplicate_not_accepted is not HTTP 409. It arrives asynchronously on the status object after a 202 create.

Support

Send the X-Request-Id response header, submission_id, external_reference, and environment. Do not send the raw request body in tickets that may be forwarded to shared channels.