Error Codes
All Aforo API errors follow RFC 7807 (Problem Details). Every error response includes a type, title, and detail field.
HTTP Status Codes
The request body is malformed or missing required fields.
Resolution: Check the request body against the API spec. Ensure all required fields are present and have the correct type.
Missing or invalid Authorization header.
Resolution: Include a valid Bearer token: Authorization: Bearer sk_live_xxx. Check your API key has not been revoked.
Authenticated but insufficient role.
Resolution: Your API key lacks the required role (OWNER, ADMIN, or BILLING_ADMIN). Contact your workspace admin.
The requested resource does not exist or belongs to a different tenant.
Resolution: Verify the entity ID. Cross-tenant requests return 404, not 403, to prevent ID enumeration.
The operation conflicts with existing state.
Resolution: Common causes: duplicate name, concurrent bill run, or an entity that blocks deletion. See the error message for specifics.
Validation failed — the data is well-formed but fails business rules.
Resolution: Check the errors array in the response body for field-level validation messages.
Too many requests. Rate limit exceeded.
Resolution: Back off and retry with exponential jitter. Check the Retry-After header for the recommended wait time.
An unexpected error occurred on the server.
Resolution: This is a platform bug. Contact support@aforo.ai with your request ID from the X-Request-Id response header.
The service is temporarily unavailable.
Resolution: Check the Aforo status page. Retry with exponential backoff. Most 503s resolve within 30 seconds.
Billing-Specific Errors
These error codes appear in the code field of a 409 or 422 response from billing endpoints.
METRIC_BLOCKED
Metric has active subscriptions and cannot be deleted.
Resolution: Cancel or migrate all subscriptions referencing this metric first.
PRODUCT_STALE
Product gateway mapping is stale — the product was deleted at the gateway.
Resolution: Use the "Restore to Gateway" action or manually re-create the gateway entity.
SUBSCRIPTION_TERMINAL
Cannot modify a CANCELLED or EXPIRED subscription.
Resolution: Create a new subscription instead.
BILL_RUN_CONFLICT
A bill run is already in progress for this tenant and period.
Resolution: Wait for the current run to complete before starting another.
WALLET_INSUFFICIENT
Wallet balance is insufficient for the operation.
Resolution: Top up the wallet before retrying.
MATURITY_TRANSITION_INVALID
The requested maturity stage transition is not allowed.
Resolution: Check allowed transitions: EXPERIMENTAL→BETA→GA→DEPRECATED→RETIRED. Retired is terminal.