Troubleshooting

HTTP status decoder, webhook debugging, and the most common integration failures.

HTTP status decoder

Code	What it means	Most common cause
200	Success, no new record created	Idempotent replay — request already processed
201	Success, new record created	First-time request
400	Bad request	Missing required field, malformed JSON, invalid URL format
401	Authentication failed	Missing `Authorization` header, wrong key prefix (`ez_test_` vs `ez_live_`), revoked key
403	Authorization failed	API key valid but doesn't own the resource (e.g. account belongs to a different partner)
404	Resource not found	Wrong ID, or resource belongs to a different partner — Easy2257 returns 404 (not 403) for cross-partner access to avoid enumeration
422	Unprocessable	Semantic validation failure (e.g. solo account exists but has no linked EZ2257 user yet)
500	Server error	Internal — retry with exponential backoff

Switch on HTTP status, not on the error message text. See Errors for the response shape.

Webhook not arriving

Work through in order:

Is your endpoint reachable from the public internet? Easy2257 POSTs from AWS — no IP allowlist required, but VPN-only or strict WAF setups will block delivery.
Is the endpoint registered with the right callbackUrl? Set it per-account at POST /api/v1/solo-accounts. Endpoint URLs are also visible in the partner dashboard at /profile/partner/webhooks.
Did your endpoint return 2xx within 30s? Slow handlers are retried even if they eventually succeed. Return 2xx immediately and process asynchronously.
Check the dashboard delivery log. Every webhook attempt is recorded at /profile/partner/webhooks with HTTP status, attempt count, and final state (DELIVERED / FAILED / EXHAUSTED). After 5 failed attempts the delivery is abandoned.
Send a test ping from the dashboard. The "Test" button on each endpoint sends a signed test.ping event you can validate end-to-end.

Webhook signature verification keeps failing

This is the #1 integration bug. Five things to check:

Raw body, not parsed JSON. You must HMAC the exact bytes received. Do not JSON.parse() and re-serialize. Per-framework:
- Next.js App Router: await req.text() ✅ — not await req.json()
- Express: express.raw({ type: "application/json" }) on this route only ✅ — not express.json()
- Flask: request.get_data() ✅ — not request.get_json()
- FastAPI: await request.body() ✅ — not await request.json()
- Laravel: $request->getContent() ✅ — not $request->all()
- ASP.NET Core: Request.EnableBuffering() then read the stream ✅
Payload is {t}.{rawBody}, not just rawBody. Concatenate timestamp + . + body before HMAC-ing.
HMAC output is hex-encoded, lowercase. Not base64.
Compare in constant time. Use timingSafeEqual / hmac.compare_digest / hash_equals / CryptographicOperations.FixedTimeEquals. Direct == is a timing-attack risk.
Your secret is the per-endpoint webhook secret, not your API key. Reveal it under each endpoint at /profile/partner/webhooks.

Working code in Webhook Signatures for Node.js, Express, Python (Flask + FastAPI), PHP (Laravel + plain), and C#.

"Account has no linked EZ2257 user" (422)

You called POST /api/v1/solo-accounts/{id}/content before the creator completed onboarding. The account was provisioned but the creator has not yet verified their ID and subscribed.

Fix: Wait for the solo_account.verified webhook before making any /content calls. The intermediate subscribed_pending_id status means "paid but not yet ID verified" — do not unlock content there.

Cannot delete content (404 on DELETE)

DELETE /api/v1/solo-accounts/{id}/content/{externalContentId} looks up the depiction by externalContentId. If you originally posted the content without an externalContentId, the depiction has no key to address it by — DELETE will return { deleted: false } and the depiction will remain.

Fix going forward: always pass externalContentId on POST /content. For old rows posted without it, contact api@easy2257.com for a one-off backfill.

Stuck Veriff session (Solo Creator onboarding)

If a creator completed the Veriff scan but their account stayed at pending_id_verification longer than a few minutes, the Veriff decision webhook may not have arrived. Easy2257's GET /api/v1/solo-accounts/{id} poll endpoint falls back to a direct Veriff REST call when the DB still shows pending — calling it once usually unsticks the account.