Reference

Errors and troubleshooting

Turn authentication, validation, conflict, and dependency failures into safe operator actions.

Use status before message text

Handle the HTTP status as the stable error category. Preserve x-request-id when present so Concierge support can trace the request without receiving customer secrets.

Status	Meaning	Action
400	Invalid shape or unsupported value	Fix the request; do not retry unchanged
401	Missing or invalid credential/signature	Check key, raw-body HMAC, and timestamp
403	Valid identity lacks permission or scope	Use the correct site and least-privilege scope
404	Unavailable or intentionally non-disclosing	Check the site-to-record relationship
409	State or idempotency conflict	Reconcile before retrying
413	Payload too large	Reduce the batch or body
429	Request class is throttled	Honor Retry-After and stop parallel retries
5xx	Temporary service or dependency failure	Retry only safe/idempotent work with backoff

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

Troubleshoot signed webhooks

Most signature failures are caused by reading parsed JSON instead of raw bytes, signing a different delivery ID, or applying the CRM signature formula to a routing webhook.

1Capture only the safe delivery ID, event, status, and request ID.
2Confirm the receiver preserved the raw body bytes.
3Recompute and compare the SHA-256 digest when using CRM Webhook.
4Confirm the timestamp is ISO-formatted and within five minutes.
5Confirm the installation uses the same signing-secret version.
6Use the correct signature formula for CRM or routing.
7Run a new test delivery; do not replay a stale signed request.

Log safe evidence

Log status, request ID, delivery ID, operation, site reference, latency, and a bounded error category. Never log API keys, bearer tokens, signing secrets, raw webhook bodies, visitor messages, transcripts, or complete CRM responses.

Next guide

Rate limits and retries