← Back to documentation

Troubleshooting

Find method, authentication, validation, and delivery problems with Activity and the endpoint configuration.

5 min read

Use this workflow when PayloadRelay rejects requests or when deliveries fail.

Purpose#

Use this guide to:

  • Map an Activity outcome to the possible causes.
  • Separate a sender problem, an endpoint configuration problem, and a destination problem.
  • Examine the recovery after a fix.

Before you start#

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

Procedure#

1. Start in Activity#

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

2. Map outcome to source of failure#

Activity shows readable labels. The machine codes that follow appear in the API responses and in the CSV exports. You can also enter them in the Activity error search.

  • METHOD_NOT_ALLOWED: the HTTP method of the sender does not match the endpoint method.
  • MISSING_REQUIRED_HEADERS: a necessary endpoint header is missing or has the wrong value.
  • AUTH_FAILED: the inbound authentication failed because of wrong credentials, an expired HMAC signature, or SPF, DKIM, or DMARC enforcement on an email endpoint.
  • CAPTCHA_FAILED: a captcha token is missing or invalid, or the provider secret is wrong.
  • FIELD_VALIDATION_FAILED: a payload field does not agree with the configured validation rules.
  • REQUEST_BODY_FILTER_FAILED: the request body does not agree with a configured body filter rule.
  • IP_BLOCKED: the source IP is not on the endpoint IP allowlist. Add it in Security -> IP allowlist.
  • EMAIL_INGESTION_REJECTED: an email configuration rule or a policy rule rejected the email. The causes are an endpoint that is not an email endpoint, a body-as-payload format that PayloadRelay does not support, a missing text/plain body, or a null SMTP sender that an allowlist rejects. The errorReason field of the entry contains the detail.
  • EMAIL_INGESTION_DISABLED: a historical outcome for an email sent to a disabled endpoint. Request activity does not show a current hit on a disabled endpoint.
  • EMAIL_INGESTION_ACCEPTED: PayloadRelay accepted the email for delivery.
  • PAYLOAD_TOO_LARGE: the event is larger than the plan size limit. The limits are 256 KB for Sandbox and Solo, 512 KB for the Team trial and Team, and 1 MB for Scale. For a custom plan, the agreement of the organization sets the limit.
  • QUOTA_EXCEEDED: the monthly accepted-event quota is empty. Open Billing and read Current plan -> Monthly usage.
  • RATE_LIMITED_ENDPOINT: the request count is more than the per-minute limit of the endpoint. Read Retry-After, and wait before the next request.
  • SUBSCRIPTION_BLOCKED: the billing is past due, and the recovery period ended. Open Billing. A normal trial completion and a paid cancellation move the organization to Sandbox.
  • MALFORMED_FORM_PAYLOAD: the sender sent invalid application/x-www-form-urlencoded data.
  • MALFORMED_JSON_PAYLOAD: the request body with the application/json content type is not valid JSON.
  • MALFORMED_XML_PAYLOAD: the request body with the application/xml or text/xml content type is not valid XML. Activity records Malformed XML body. as the error reason.
  • MALFORMED_QUERY_PARAM: the query parameter parsing failed, for example, because of invalid Base64 in the query parameter mode.
  • UNSUPPORTED_MEDIA_TYPE: the incoming Content-Type does not match the endpoint format.
  • PAUSED: a historical outcome for a hit on a paused endpoint. Request activity does not show a current hit on a paused endpoint.
  • FAILOVER_TRIGGERED: a webhook destination used all its retries, and PayloadRelay activated its failover destination.
  • DELIVERY_FAILED: PayloadRelay accepted the request, but the delivery to one destination or more failed after all the retries.
  • TEST_ACCEPTED/TEST_REJECTED/TEST_RATE_LIMITED: the outcomes of the relay-target test button. This is not real traffic.

3. Examine endpoint configuration#

Read these endpoint tabs:

  • Details: the method and the payload format.
  • Filter: the request-body filters and the field-validation rules.
  • Transform: the payload transformation and the append rules.
  • Security: the inbound authentication, the captcha, the required headers, the IP allowlist, and the CORS.
  • Alerts: the failure-rate alerts and the optional auto-pause behavior.
  • Outputs: the destinations, the webhook retries, and the values for each destination.

4. Examine the relay target and endpoint output#

For a delivery failure:

  1. Open each attached relay target and make sure that its destination URL or its provider credentials are correct.
  2. For a Webhook URL target, use Test reachability to send an unauthenticated POST, PUT, or PATCH. This test does not use the destination authentication, the custom headers, the HMAC, the HTTPS enforcement, the retries, the failover, the routing, and the response forwarding. A destination with authentication can reject this reachability test, also when the destination configuration is correct.
  3. Edit the endpoint and make sure that the destination authentication, the custom headers, the HMAC signing, the Enforce HTTPS control, the outbound method, the retries, and the failover are correct.
  4. Send a representative request through the saved endpoint, and read that delivery in Activity.

If the reachability test fails, examine the selected method, the URL, and the availability of the destination. If the reachability test succeeds but the complete path fails, read the destination configuration and the destination response.

5. Recovery after a fix#

  1. Send a known-good payload again.
  2. Make sure that the outcomes go back to Completed (ACCEPTED) or Test accepted (TEST_ACCEPTED).
  3. Continue to monitor for a new occurrence.

Expected result#

  • You identified and classified the cause.
  • The outcome trend shows a recovery after the fix.

Common issues and fixes#

  • A header mismatch: a header name ignores the case, but a value is case-sensitive. PayloadRelay does not remove the spaces from an incoming value. Copy the expected value exactly.
  • The captcha continues to fail: make the token field name and the provider secret agree.
  • Intermittent delivery problems: examine the destination incidents and the rate limits.
  • No traffic after a URL rotation: give the new endpoint URL to the sender.
← Back to documentation