← 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: an email-specific setup or policy rejection, such as sending to a non-email endpoint, unsupported body-as-payload format, missing text/plain body, or a null SMTP sender rejected by an allow-list. The specific reason is in the entry's errorReason field.
  • EMAIL_INGESTION_DISABLED: historical outcome for email sent to a disabled endpoint. Current disabled endpoint hits are omitted from request activity.
  • EMAIL_INGESTION_ACCEPTED: email accepted into the relay pipeline.
  • PAYLOAD_TOO_LARGE: event exceeded the maximum allowed size for your plan (256 KB Sandbox/Solo, 512 KB Team trial/Team, 1 MB Scale).
  • QUOTA_EXCEEDED: monthly accepted-event quota is exhausted. Check Billing → Usage.
  • RATE_LIMITED_ENDPOINT: the endpoint's per-minute rate limit was exceeded. Check Retry-After header and back off.
  • SUBSCRIPTION_BLOCKED: billing is past due and the recovery grace period ended. Check Billing. Normal trial completion and paid cancellation move the workspace to Sandbox instead.
  • 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: historical outcome for paused endpoint hits. Current paused endpoint hits are omitted from request activity.
  • FAILOVER_TRIGGERED: a webhook output exhausted all retries and its failover destination 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 and payload format.
  • Security: inbound auth, captcha, required headers, CORS.
  • Field validation: rules and patterns.
  • Target destinations: outputs, webhook retries, 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