Skip to main content

Troubleshooting and FAQ

Use this page when a Conduit integration is failing in development, staging, or production. Start with the symptom that matches your issue, fix the highest-probability cause first, then jump to the linked workflow, API reference, or recipe for the deeper recovery path.

Quick triage​

SymptomMost likely causeStart here
401 or 403 on every requestMissing API key, wrong API key, or server-side env wiring issueAuthentication and API key errors
Webhook returns 401 or signature verification failsParsed JSON before verification, wrong webhook secret, or wrong raw body handlingWebhook verification and delivery issues
Job accepted but no report stored locallyDelivery failure, missed completion handling, or reconciliation gapFailed jobs and missing reports
400, 415, or 422 on create or uploadUnsupported input, invalid request shape, or target/template mismatchBad inputs and validation failures
429 responses or exhausted request budgetPolling too aggressively or request burst above current limitsRate limits and retry pressure

Authentication and API key errors​

If every request fails with 401 or 403, start with credential wiring instead of retries.

  • Confirm you are sending CONDUIT_API_KEY from a server-side environment, not from a browser client.
  • Check the request header and environment mapping used by your SDK or direct REST client.
  • Treat auth failures as configuration problems. Do not retry them with backoff.
  • Capture the requestId from API or SDK errors when you need support help.

Go deeper:

Webhook verification and delivery issues​

Most webhook failures come from one of three causes: verifying the wrong body, using the wrong secret, or treating delivery problems as if the job itself failed.

  • Verify against the exact raw request body before parsing JSON.
  • Check the conduit-signature header and the correct CONDUIT_WEBHOOK_SECRET for the environment receiving deliveries.
  • Return success quickly after verification, then move heavier work off the request path.
  • Deduplicate retries on event.id so duplicate deliveries are harmless.
  • If a job completed but your app did not record it, reconcile by jobId or reportId before resubmitting work.

Go deeper:

Failed jobs and missing reports​

Separate processing failures from delivery failures.

  • If you receive report.failed, persist the jobId, error code, and error message before deciding whether to submit a new request.
  • If webhook delivery failed, check the current job state before assuming the job itself failed.
  • Use GET /v1/reports/by-job/:jobId to reconcile completed work. It returns null until a completed report exists.
  • Keep your own request correlation id and idempotencyKey with the accepted jobId so you can recover cleanly.

Go deeper:

Bad inputs and validation failures​

Request-shape failures usually recover faster when you inspect the input path, not when you add retries.

  • For 400 or 422, verify the request body matches the current source, output, webhook, and targeting shapes.
  • For 415 unsupported_media_type, confirm you are using a supported ingestion path and media type.
  • If targeting fails, verify that your targeting strategy matches the media you submitted and the speaker-selection behavior you expect.
  • If you are migrating from older patterns, prefer the current report job workflow over removed analyze routes.

Go deeper:

Rate limits and retry pressure​

429 usually means the integration is spending budget on avoidable polling or sending create bursts faster than the current limit window allows.

  • Prefer verified webhooks over aggressive polling loops.
  • Read X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset before you decide how fast to retry.
  • Retry transient 429 and 5xx failures with bounded backoff.
  • Do not retry auth or validation errors as if they were rate-limit events.

Go deeper:

Retries and idempotency FAQ​

Should I poll or use webhooks?​

Use webhooks as the default production completion path. Polling is acceptable for local development, controlled internal tooling, and one-off backfills when you cannot expose an HTTPS endpoint yet.

Can I resend the same create request?​

Yes, if it is the same logical create request. Reuse the same idempotencyKey for intentional retries of that request. Do not generate a fresh key unless you mean to create new work.

Why did my webhook arrive twice?​

Webhook delivery retries are normal recovery behavior. Deduplicate on event.id and make downstream writes safe to repeat.

Go deeper:

What to collect before contacting support​

When self-serve recovery does not resolve the issue, gather the smallest useful debugging bundle before you escalate:

  • requestId from the API or SDK error
  • jobId for the accepted async request
  • reportId if a completed report exists
  • event.id for webhook-delivery debugging
  • HTTP status, error code, and timestamp
  • Whether the failure happened on create, webhook delivery, report fetch, or reconciliation

Useful references: