Troubleshooting

A quick reference for the most common issues developers encounter when integrating HeyVisa. If your problem is not listed, contact support@heyvisa.com with the request ID from the response headers.

Common cases

401 unauthorized on every request

Problem

All calls return 401 with code invalid_key.

Cause

The key prefix does not match the environment (e.g.,hv_test_ sent to a live-only endpoint), or the key was revoked from the dashboard.

Solution

Verify the key in Settings → API Keys. Recreate it if necessary and roll out via your secrets manager.

Reports stuck in queued forever

Problem

POST /v1/reports returns queued but never transitions.

Cause

Webhook URL is unreachable (firewall, expired TLS cert) and the client is not polling either.

Solution

Check Settings → Webhooks → Delivery log. Fix the endpoint or remove webhook_url from the payload and switch to polling GET /v1/reports/{id}.

Webhook signature verification fails

Problem

v1 never matches the computed HMAC.

Cause

The request body is being parsed as JSON before verification. Re-serialised JSON has different whitespace and breaks the signature.

Solution

Capture the raw body. In Express, use express.raw({ type: "application/json" }); in Flask, call request.get_data().

OCR returns garbled fields for a scanned passport

Problem

Extracted passport_number contains spaces or wrong characters.

Cause

The image was uploaded at low resolution (< 200 DPI) or with heavy compression artefacts.

Solution

Re-scan at 300 DPI minimum and upload as PDF or PNG. The dashboard preview shows the effective resolution of every uploaded file.

Sudden burst of 429 errors after deploy

Problem

Pipeline that previously worked now sees frequent 429 rate_limited.

Cause

A loop or migration script is firing single-report calls in parallel above your plan's concurrency limit.

Solution

Move to batch submissions (one batch counts as one request), or implement exponential backoff respecting Retry-After.

Always grab the request ID

Every response includes X-Request-Id. Include it when you contact support — it lets us trace the request through every stage of the pipeline in seconds.