Skip to main content

Troubleshooting

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

API Errors​

401 Unauthorized — "API key missing or invalid"​

Cause: The Authorization: Bearer {apiKey} header is missing, malformed, or the API key has been revoked or has expired.

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), each with an expiry — a response served with a key nearing rotation age carries a Warning: 299 header, and an expired or revoked key returns 401. Rotate before expiry.
# 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), targets a company other than its own (FORBIDDEN_COMPANY), 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 correct key for its own company account.

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

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 all /api/* routes, a per-IP route limit of 100 requests/minute on GET /api/dpp/{slug} (so the effective public-DPP ceiling is 100/minute), and a per-API-key limit of 100 requests/minute on the Integration API (/api/v1), counting reads and writes, with separate live and sandbox quotas. GET /api/health is exempt.

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.

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED"
}

503 — Health endpoint returns "status": "degraded"​

Cause: One of the platform's backing services (database or cache) is experiencing connectivity issues.

Resolution: Check the services object in the response to identify which service is affected. 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.
  • Status filter: by default, archived products are hidden. If you archived products, they won't appear unless you select "Archived" in the status filter.
  • 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 https://app.traceable.digital/dpp/<slug>.

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: Compliance score considers three components: field population, attached documents, and verification task completion. You can have all fields filled but score below 100% if:

  • No compliance document is attached (navigate to Compliance → Documents and upload at least one)
  • No verification task has been completed with an "Approved" outcome (navigate to Verification → Create Task, assign a verifier, and complete the review)

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. Send a reminder via the data request page (Suppliers → [Supplier] → Data Requests → [Request] → Send Reminder).
  2. If the supplier is unresponsive, you can manually enter the data yourself or mark the fields as "Not available" with a note.
  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 team member is removed​

Cause: API keys are associated with the company account, not the individual user who created them. Removing a team member does not automatically revoke their API keys.

Resolution: If a team member with API key access leaves the organisation, navigate to Settings → API Keys, review all active keys, and revoke any that were created for that individual's integration use.

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.