Testing and go-live

Troubleshooting

Common errors when integrating Limenia and how to fix them — API answers, webhook signatures, deliveries, connectors and media.

API answers

Symptom Cause Fix
401 unauthenticated Key missing, mistyped, revoked, or the header is not Authorization: Bearer <key> Check $LIMENIA_API_KEY with GET /v1/ping; create a new key if it was revoked. Do not sign your app user out.
403 tenant_not_active The setup wizard of the tenant is not finished An owner finishes it in the dashboard; it can take up to 30 s to take effect.
400 validation_failed with field Idempotency-Key The header is missing, empty, longer than 200 characters or sent twice Send exactly one key of 1 to 200 characters.
400 validation_failed at /subject Neither subject nor content was sent Send at least one; with content always its author as subject.
400 validation_failed at /goodFaith goodFaith sent with source: system Send goodFaith only with source: user.
400 bad_request Invalid JSON, a wrong type, a date that is not RFC 3339, or a body over 1 MiB Validate the body; send media as URLs, not inline.
404 not_found on GET /v1/appeals/{appealId} or a decision The ID belongs to another app (another API key) or a typo Use the key of the app the decision belongs to.
404 not_found for a path Wrong base URL, e.g. /v1 twice LIMENIA_BASE_URL is https://app.limenia.eu without /v1.
409 idempotency_key_reused The same key was used for a different body Derive the key from your own request ID; never reuse it for another request.
429 rate_limited More than 10 requests per second per key Wait Retry-After, batch signals, queue spikes of review requests.
403 feature_not_in_plan, 402 subscription_required Reviews, signals or device checks are not in the plan or the subscription expired An owner changes the plan; reports and complaints keep working.
403 reporter_suspended The reporter’s reports are suspended (Art. 23 DSA) Show suspendedUntil; do not retry.
409 appeal_window_closed, appeal_already_open Six months passed, or the person already has an open complaint Show the reason to the user.
403 appeal_not_allowed E.g. the affected user complains against dismiss, or someone who did not report the case complains as reporter Offer complaints only to the people who may complain (see Complaints).
400 review_type_unknown, signal_type_unknown The code is not an active type of this app Create or activate the type in the dashboard (tab Moderation).
Requests time out after a pause The first request after a quiet period can be slower Use a client timeout of about 30 s and retry.

Webhook signature fails

  • The body was parsed before verifying. Frameworks that parse JSON first (Express express.json(), JSON.stringify(req.body), Laravel $request->all()) change bytes. Verify over the raw body: express.raw(), req.rawBody in Cloud Functions, await req.arrayBuffer() in Deno, $request->getContent() in Laravel, await request.body() in FastAPI.
  • Wrong secret. The secret is the whole string including whsec_. After Rotate secret the old one stops working at once: accept both during the switch (LIMENIA_WEBHOOK_SECRET_PREVIOUS).
  • timestamp_out_of_range. Your server clock is off by more than 300 seconds; sync it with NTP. The documentation test vector always fails this check unless you inject the clock.
  • Hex compare. v1 is lower-case hex of the HMAC; compare the decoded bytes or the hex strings in constant time.
  • Body decoded on Lambda. Decode event.body when event.isBase64Encoded is set before verifying.

Webhooks do not arrive

  • The webhook is not active. Without URL and secret, or when switched off, decisions are not delivered, also not later. Reconcile with GET /v1/subjects/{externalUserId}/status.
  • blocked_url. The URL resolves to a private or internal address. Use a public HTTPS endpoint.
  • http_status 3xx. Limenia does not follow redirects: enter the final URL (watch out for http to https and trailing-slash redirects).
  • http_status 401 or 403. An auth middleware or a firewall in front of your route blocks Limenia. The webhook route must be public; the signature is the authentication. Limenia sends from no fixed IP address, so IP allowlists do not work.
  • timeout. Answer within 10 seconds; store the event and process it asynchronously.
  • Deliveries are failed. After 12 attempts (about 20 hours) Limenia gives up. Fix the receiver, then resend from the Delivery log.
  • Events arrive twice or out of order. That is expected: deduplicate by event ID and skip events older than the last applied change (see Answers, retries, order).

Connectors

  • user_not_found (Firebase, Supabase) or revenuecat_customer_not_found. The externalUserId you send is not the user ID of that service. The connector needs the Firebase UID, the Supabase user UUID or the RevenueCat App User ID.
  • ownership_not_proven (Firebase). The project label limenia-tenant=<tenant ID in lower case> is missing.
  • Banned users stay signed in. Issued tokens stay valid up to an hour; check revocation where bans must take effect at once (see Firebase connector, Supabase connector).
  • invalid_device_token. The token was decoded before (Android tokens must be forwarded unchanged), the request hash does not match, the token is older than 15 minutes, or an iOS debug build was sent without environment: "development".
  • device_connector_not_configured. The platform is not switched on for the app, or a test token was sent without test mode.

Media are missing in a case

  • The URL must be fetchable with a plain GET without login for at least an hour (e.g. a signed URL), over https, from a public address, with at most 3 redirects.
  • At most 20 MB per file; supported are JPEG, PNG, GIF, WebP, MP4, WebM and QuickTime. HEIC, HEIF and AVIF are not supported.
  • For child_safety and protection_of_minors Limenia keeps no copy on purpose.
  • See Media.

Identifiers are discarded

Ban evasion across apps is coming soon and discards identifiers until it is enabled for your tenant. Once enabled, compare the check values in the dashboard with your implementation (see Self-test with the check values).