Skip to main content

Troubleshooting

Common errors and their resolutions for API integrations and the operator portal.

API Errors​

401 Unauthorized​

Cause: The Authorization: Bearer {apiKey} header is missing, malformed, or the API key has been revoked or has expired. The error message is Missing or malformed Authorization bearer token. (code UNAUTHENTICATED) or API key is invalid, revoked, or expired. (code INVALID_API_KEY).

Check:

  1. Confirm the Authorization header is present and formatted exactly as Bearer <key> (note the space, not an equals sign).
  2. Verify the API key is active in Settings → API Keys: revoked keys return 401 immediately.
  3. API keys are case-sensitive and must be copied in full. Keys are pk_live_… (live) or pk_test_… (sandbox). A key may carry an optional expiry chosen when it is generated (30 days, 90 days, 1 year, or never). Whether or not it has an expiry, a response served with a key older than 90 days carries a Warning: 299 header, and an expired or revoked key returns 401. Rotate keys on a schedule.
# Correct
curl -H "Authorization: Bearer pk_live_a1b2c3d4..."

# Incorrect: missing Bearer prefix
curl -H "Authorization: pk_live_a1b2c3d4..."

403 Forbidden: "API key lacks the required scope or module"​

Cause: The API key is valid but lacks a scope or module the endpoint requires (FORBIDDEN_SCOPE / FORBIDDEN_MODULE), or is the wrong mode for the endpoint (CROSS_MODE_DENIED, for example a sandbox key on a live-only GDPR endpoint).

Resolution: Confirm the key carries the scopes your integration needs and that you are using the right key for the mode (live or sandbox) of the endpoint.

Cross-tenant resources return 404, not 403

Requesting an unknown resource, or a resource owned by another tenant, returns 404: never a 403 "exists but forbidden". The API never confirms that another tenant's data exists (no existence oracle). A key issued for Company A cannot see Company B's products, and such a lookup is indistinguishable from a genuinely unknown id.

404 Not Found on GET /api/dpp/{slug}​

Cause: One of the following:

  • The product slug is incorrect (slugs are case-sensitive)
  • The product exists but has not yet been published: draft products are not accessible via the public API
  • The product has been unpublished, or was revoked by a regulator

A withdrawn or deprecated product that was published before, and a published product whose manufacturer is suspended or inactive, is not a 404: it answers 200 with an availability block. See Archived passports.

Check:

  • Verify the slug exactly as it appears in the operator portal URL for the product
  • Confirm the product status is Published (green badge in the product list)

429 Too Many Requests​

Cause: Rate limit exceeded. Limits apply in three layers: a per-IP edge limit of 120 requests/minute on /api/* routes (GET /api/health and GET /api/dpp/{slug}/jsonld are exempt from this layer), a per-IP route limit of 100 requests/minute on the public DPP routes (so the effective public-DPP ceiling is 100/minute), and a per-API-key limit of 100 requests/minute per operation family on the Integration API (/api/v1), counting reads and writes, with separate live and sandbox quotas. Three product reads (GET /api/v1/products, GET /api/v1/products/{id} and GET /api/v1/products/{id}/gate) are not counted against the per-key limit.

Resolution: Inspect the Retry-After header in the 429 response. It gives the number of seconds to wait before retrying. There is no retryAfter field in the response body; read the header. Implement exponential backoff with jitter for sustained integrations. See Rate Limiting for p-queue configuration examples.

The body of a 429 from the public DPP routes is:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Try again later."
  }
}

The per-IP edge limiter answers with {"error":"Too many requests"} instead, with no code.

Health endpoint does not return 200​

Cause: The platform is unreachable or failing. GET /api/health is a static liveness check, so it does not report on individual services such as the database or the cache.

Resolution: Retry with exponential backoff. Subscribe to Traceable's status updates via the Changelog for incident notifications (RSS feed: https://dev.traceable.digital/changelog/rss.xml).

BMS Endpoint: BAD_SIGNATURE​

Cause: The HMAC-SHA256 signature does not match. Common causes:

CauseFix
Timestamp outside the 5-minute replay windowEnsure the signing timestamp is generated immediately before the request, not cached
Body was re-serialisedBuild the JSON body string once and use the same string for both signing and the HTTP body
Whitespace difference between signed and sent bodyUse the same serialisation (e.g. JSON.stringify with no extra spaces)
Wrong secretConfirm the X-Traceable-BMS-Secret header contains the same secret used as the HMAC key

See BMS Endpoints for the reference signing implementations.

Operator Portal Issues​

Products not appearing in the list​

Check:

  • Active filters: the filter bar may be excluding your products by category, status, or compliance score range. Click Clear all to reset.
  • Account access: confirm you are logged into the correct company account if you have access to multiple tenants.

Document AI extraction returns low confidence scores​

Cause: The uploaded document may be a scanned image (not a text-based PDF), have low resolution, use non-standard fonts, or contain handwritten content.

Resolution:

  1. Where possible, use text-based PDFs from the original document source rather than scans.
  2. For scanned documents, ensure the scan resolution is at least 300 DPI.
  3. Low-confidence fields are flagged for review. Manually verify and correct the extracted value before accepting.
  4. If extraction consistently fails for a specific document type, contact support@traceable.digital with a redacted sample.

QR code does not resolve after publishing​

Cause: DNS propagation or CDN cache delay after initial publishing. QR codes resolve to the passport host: https://dpp.traceable.digital/01/{GTIN} (with /21/{serial} for an item) when the product has a GTIN, or https://dpp.traceable.digital/dpp/<slug> when it has none.

Resolution: Wait 60 seconds after publishing and retry. If the QR code still does not resolve after 5 minutes, verify:

  1. The product status shows Published in the portal
  2. GET /api/dpp/<slug> returns a 200 response (this confirms the data is live)
  3. If the API returns 200 but the QR URL 404s, contact support@traceable.digital

Compliance score is stuck below 100% despite all fields being filled​

Cause: The compliance score is calculated from how many required fields are filled (60%) and the status of your certificates (40%). You can have all fields filled but score below 100% if:

  • A required certificate is not attached to the product
  • A certificate has not yet been verified (a certificate becomes Verified when a verifier approves its document)

Check the compliance score breakdown on the product dashboard; it lists which component is incomplete.

Supplier data request shows "No response" after the deadline​

Cause: The supplier did not respond within the deadline period. The request status changes to "Overdue" but is not automatically closed.

Resolution:

  1. Follow up with the supplier directly, using the contact details on the supplier's page under Suppliers.
  2. If the supplier is unresponsive, you can enter the data yourself.
  3. For suppliers who have not activated their Traceable account, check that the invitation email was received (check the supplier's spam folder) and resend if needed.

Account & Access Issues​

Team member cannot see certain features​

Cause: Feature visibility in the operator portal depends on the team member's role and on which modules are active for your company account. See Module Access for details on module gating.

Resolution: Check Settings → Team Management to confirm the team member has the appropriate role. If the feature appears greyed out or locked, it may require module activation. Contact support@traceable.digital.

API key stops working after a team member is removed or demoted​

Cause: When a team member is removed from the company, every active API key they created is revoked automatically, and the key then returns 401. The same happens when a member's role changes so that they can no longer manage API keys.

Resolution: Mint a replacement key from Settings → API Keys under a member who still has key-management access, update the integration, and review the remaining keys.

Getting Help​

If you cannot resolve an issue using this guide:

  • Changelog: Check the Changelog for recent platform changes that may have affected your integration. An RSS feed is available at https://dev.traceable.digital/changelog/rss.xml.
  • Email support: support@traceable.digital. Include your company name, the affected product slug or API endpoint, and the full error response body.
  • Security issues: For security vulnerabilities, see the Vulnerability Disclosure policy.
Was this page helpful?
Last updated on