Troubleshooting

This page lists common errors, causes, and suggested fixes.

Common errors

401 Unauthorized — Missing or invalid Authorization: Bearer <ENV_TOKEN> header. Regenerate or copy a correct environment token from the portal.
400 idempotency_key_required — Idempotency-Key header missing for POST /events. Add a UUID header.
400 invalid_idempotency_key — Provided Idempotency-Key is not a UUID.
409 Idempotency conflict — Same Idempotency-Key used with different body. Use a fresh key.
422 Validation failed — Payload didn’t match the required schema; inspect details in response.
429 Too Many Requests — Rate limits exceeded; respect Retry-After header and back off.

Signature invalid — Check that you’re using the correct secret and computing HMAC over {X-SP-Timestamp}.{raw_body}. Ensure clock skew is within 5 minutes.
Non-2xx responses — Check endpoint health and response body; portal shows attempt logs and failure reasons.
Timeouts — Webhooks have a 30s timeout; respond quickly or return a lightweight 200 if you queue work.

Provider authentication errors — verify credentials in Provider Connections and test the connection in the portal.
Template too large — rendered template exceeds 100KB. Reduce template size or attachments.

Use the Message detail view in the portal to inspect delivery_runs, attempts, timestamps, and raw payloads.
When contacting support include: message_id, delivery_run_id, timestamps, the failing endpoint, and an example response body.

Use replay when the remote endpoint is restored; replays respect idempotency rules and will not double-count usage if the original delivery previously failed.