Sign in →
Troubleshooting1 min read

Troubleshooting — Overview

Common failures and what to do about them. Common Issues for the everyday "why is this not working," Rate Limits for the 429-shaped ones.

Updated 2026-06-30Suggest edits
Docs Troubleshooting Overview

Something not working? Start here. This section is the short list of failure modes that account for the majority of support tickets — wrong API key, wrong tenant header, rate limit hit, billable unit not declared, the usual. Two pages: Common Issues for everything, Rate Limits for the 429-shaped subset.

What this section is for#

Fast triage. Most "it isn't working" problems fall into one of a handful of patterns — Troubleshooting captures those patterns with the steps to confirm and the fix. When the answer isn't here, the next stop is Error Codes or the live + Event Log in the console.

Pages in this section#

First five things to check#

Before you go deeper, run these five checks — they catch most issues in under a minute:

1
Is the API key prefixed sk_live_ or sk_test_?
A sandbox key against a production endpoint returns 401. Confirm the prefix matches the base URL.
2
Is X-Tenant-Id present on every request?
Missing tenant header is a 400. The header value is your tenant identifier, not your tenant name.
3
Does the billable unit exist in this tenant?
POST /v1/meter rejects unknown unit names with HTTP 422 + code UNKNOWN_METRIC. Catalog → Billable Units is where it gets created.
4
Are you hitting the right base URL?
Sandbox is sandbox.aforo.ai, production is api.aforo.ai. Mixing them returns 401 / 404 in confusing combinations.
5
Has the change actually deployed?
The Aforo Changelog records every public change. Operator-side, the Audit Log shows config changes within seconds.

Where to look by symptom#

SymptomWhere to look
401 Unauthorized on every callCommon Issues → API key + tenant header section
429 Too Many Requests on a single endpointRate Limits — per-endpoint table
422 UNKNOWN_METRICCommon Issues + Catalog → Billable Units (declare the unit)
Webhook signature does not verifyCommon Issues → Webhook signature debugging
Dashboard shows zero on a metric you know is firingOperations → Metering Health (NO_DATA card) + Event Log
Invoice line item missing or wrongPricing Studio → Billing & Invoicing (10-stage pipeline reference) + Audit Log
Subscription stuck in a statusPricing Studio → Subscriptions (state machine reference)
Outbound webhook never deliveredOperations → Alerts & Notifications → Delivery Log

When to file a ticket#

File a ticket through your customer's storefront support page when:

  • You've walked the five checks above and the issue still reproduces.
  • The Error Codes page lists the code you're seeing but the suggested fix didn't work.
  • The behaviour contradicts what's documented (a doc bug is a real bug; we'd like to know).
  • You can reproduce reliably and have a correlation id (Aforo error bodies carry one in instance).
PRO TIP
Include the request id from the error envelope, the timestamp (UTC), the tenant id, and the smallest reproducible curl. Tickets with all four typically get a response within the documented SLA; tickets without them tend to go back-and-forth for clarification first.

Self-service paths before filing

  • API Reference → Try-It-Out to confirm the expected request shape works.
  • Error Codes → look up the exact code in the response.
  • Operator console → Event Log → search for your correlation id.
  • Operator console → Audit Log → recent changes that might have caused the regression.