← Back to documentation

Troubleshooting Ingest

Diagnose 400, 401, 413, 429, and 503 errors using the Activity log and filters.

4 min read

This page covers the most common errors you'll see when sending data to a PayloadRelay relay URL and what to do about each.

Where to look first

Open Activity in the dashboard. Every ingest attempt is logged with:

  • Status — the HTTP response code returned to the caller.
  • Outcome — ACCEPTED, AUTH_FAILED, METHOD_NOT_ALLOWED, IP_BLOCKED, PAUSED, etc.
  • Timestamp — when the request arrived.

Use the Filters panel to narrow by endpoint, status, date range, or outcome. See Observability for full filter details.

401 Unauthorized

Cause: The inbound auth check failed. The endpoint requires authentication but the request either omitted the auth header or supplied incorrect credentials.

Resolution:

  1. Open the endpoint's edit page and check Security → Inbound Auth.
  2. Confirm the auth type (Basic / Bearer / API key) and the configured header name.
  3. Resend with the correct header. Examples:
    • Authorization: Bearer YOUR_TOKEN
    • Authorization: Basic <base64(user:pass)>
    • X-Api-Key: YOUR_KEY (or your configured header name)

See Sending Data for language-specific examples with auth headers.

413 Payload Too Large

Cause: The request body exceeds the maximum allowed size.

Resolution: Reduce the payload size. If you need to send large binary files, consider uploading to object storage (S3, GCS, etc.) and sending only the reference URL via PayloadRelay.

400 Bad Request — Content validation failed

Cause: The request passed auth but failed content validation. Common sub-causes:

  • A required header declared on the endpoint is missing from the request.
  • A body filter rejected the payload (for HTTP webhooks this logs REQUEST_BODY_FILTER_FAILED; for email body-as-payload it logs EMAIL_INGESTION_REJECTED).
  • A field validation rule failed (e.g., a field is required but null, or fails a regex pattern).

Body filters run against the raw decoded request body for JSON/XML/text, the raw form body for form endpoints, and the raw query string for query-parameter formats. Multiple body filter rules are ANDed: every rule must pass.

Resolution:

  1. Check the Activity log entry — the outcome field often includes a hint.
  2. Open the endpoint's Security tab and verify required headers. Header names are case-insensitive, but values are case-sensitive and incoming values are not trimmed.
  3. Open the Filter tab and review body filters and field validations.
  4. Add the missing headers or fix the payload to satisfy the configured rules.

429 Too Many Requests

Cause: One of two rate-limiting mechanisms triggered:

  1. Monthly quota exhausted — Your subscription's monthly request limit has been reached.
    • Resolution: Check Billing → Usage for your remaining quota and reset date. Upgrade your plan if you need a higher limit.
  2. Per-endpoint rate limit exceeded — The endpoint's per-minute request cap was hit (configured in the endpoint's Details tab).
    • Resolution: Wait for the Retry-After header value (in seconds) and retry. Consider increasing the endpoint's per-minute limit or batching requests at the sender.

For both cases, implement exponential back-off in your sender: when you receive a 429, read the Retry-After header (if present), wait, then retry.

503 Service Unavailable — Endpoint Paused

Cause: The endpoint has been paused temporarily without being fully disabled.

Resolution:

  1. Open the endpoint's edit page.
  2. Click Resume in the pause control at the top of the form.
  3. Alternatively, if the endpoint was scheduled for auto-resume, wait for the pause window to expire.

Endpoint disabled (no response / 404)

Cause: The endpoint is fully disabled (toggle is off).

Resolution: Open the endpoint and flip the Enabled toggle back on.

General debugging tips

  • Use the Activity log with outcome = AUTH_FAILED filter to isolate auth problems.
  • Use curl -v to inspect exactly which headers are being sent.
  • Compare your request to the snippets shown on the endpoint edit page — they pre-fill the correct auth header and required headers for your configuration.
  • For persistent issues, open a support ticket via the Support page.

Next steps

← Back to documentation