← Back to documentation

Troubleshooting

Fast triage workflow for method mismatches, auth failures, validation errors, and delivery issues.

10 min read

Use this workflow when requests are rejected or deliveries fail.

Purpose

This guide helps you:

  • Map Activity outcomes to likely root causes.
  • Separate sender issues from endpoint config issues and destination issues.
  • Validate recovery after fixes.

Prerequisites and permissions

  • Access to Request activity.
  • Access to endpoint and relay-target editing pages.

Step-by-step workflow

1. Start in Activity

  1. Open Request activity.
  2. Filter to affected endpoint.
  3. Open Request Log and inspect Errors.
  4. Capture timestamp range, outcome, and error reason.

2. Map outcome to source of failure

  • METHOD_NOT_ALLOWED: endpoint method mismatch — sender HTTP method does not match the endpoint's configured method.
  • MISSING_REQUIRED_HEADERS: missing/incorrect required headers declared on the endpoint.
  • AUTH_FAILED: inbound auth mismatch — wrong credentials, expired HMAC signature, or SPF/DKIM/DMARC enforcement failure (email endpoints).
  • CAPTCHA_FAILED: missing/invalid captcha token or bad provider secret.
  • FIELD_VALIDATION_FAILED: payload fields fail configured validation rules (wrong type, missing required field, regex mismatch).
  • REQUEST_BODY_FILTER_FAILED: request body fails a configured body filter rule.
  • IP_BLOCKED: the originating IP address is not on the endpoint's IP allowlist. Add it under Security → IP allowlist.
  • EMAIL_INGESTION_REJECTED: any email ingestion failure — disabled endpoint, allowed-sender mismatch, SPF/DKIM/DMARC enforcement failure, body-filter or field-validation failure in body-as-payload mode, etc. The specific reason is in the entry's errorReason field.
  • EMAIL_INGESTION_DISABLED: email sent to an endpoint that does not have email ingestion enabled.
  • EMAIL_INGESTION_ACCEPTED: email accepted into the relay pipeline.
  • PAYLOAD_TOO_LARGE: request body exceeded the maximum allowed size for your plan (256 KB Trial/Basic, 512 KB Pro, 1 MB Ultimate).
  • RATE_LIMITED_ENDPOINT: the endpoint's per-minute rate limit was exceeded. Check Retry-After header and back off.
  • MALFORMED_FORM_PAYLOAD: sender posted invalid application/x-www-form-urlencoded data.
  • MALFORMED_JSON_PAYLOAD: request body with application/json content type was not valid JSON.
  • MALFORMED_XML_PAYLOAD: request body with application/xml or text/xml content type was not valid XML. Activity logs Malformed XML body. as the error reason.
  • MALFORMED_QUERY_PARAM: query parameter parsing failed (e.g., invalid Base64 in query parameter mode).
  • UNSUPPORTED_MEDIA_TYPE: the incoming Content-Type does not match what the endpoint expects.
  • PAUSED: the endpoint was paused when the request arrived (manually, by auto-pause alert, or during a maintenance window).
  • FAILOVER_TRIGGERED: a webhook output exhausted all retries and its failover target was activated.
  • DELIVERY_FAILED: request accepted but delivery to at least one output failed after all retries.
  • TEST_ACCEPTED/TEST_REJECTED/TEST_RATE_LIMITED: relay-target test button outcomes (not real traffic).

3. Validate endpoint config

Check endpoint tabs:

  • Details: method, payload format, retries.
  • Security: inbound auth, captcha, required headers, CORS.
  • Field validation: rules and patterns.
  • Target destinations: outputs and per-output options.

4. Validate relay-target config

For delivery failures:

  1. Open each attached target.
  2. Verify URL, auth mode, headers, SSL enforcement.
  3. Run Send test.

If tests fail too, destination-side configuration/availability is usually the issue.

5. Confirm recovery

  1. Re-test with known-good payload.
  2. Verify outcomes move back to ACCEPTED/TEST_ACCEPTED.
  3. Continue monitoring for recurrence.

Expected result and verification checks

  • Root cause is identified and categorized.
  • Fix is confirmed by outcome trend improvement.

Common issues and fixes

  • Header mismatches: header names are case-insensitive, but values are case-sensitive and incoming values are not trimmed; copy the expected value exactly.
  • Captcha still failing: align token field name and provider secret.
  • Intermittent delivery failures: check destination incident windows/rate limits.
  • No traffic after URL rotation: update sender to the new endpoint URL.

Related guides

← Back to documentation