HTTP API and errors

The endpoints the SDK calls, for any language. Base URL https://www.usagegate.io, and every request sends Authorization: Bearer <your API key>. Machine-readable version: OpenAPI.

Check: may this user do it?

GET /api/v1/check

GET /api/v1/check?userId=user_123&feature=export_pdf
→ 200 { "allowed": true, "balance": 1, "feature": "export_pdf", "userId": "user_123" }

Consume: spend some

POST /api/v1/consume

POST /api/v1/consume
{ "userId": "user_123", "feature": "ai_credits", "amount": 1 }
→ 200 { "allowed": true, "remaining": 9, ... }

Checks and spends in one step. Not enough left is still a 200, with "allowed": false.

Grant plan: put a user on a free plan

POST /api/v1/grant-plan

POST /api/v1/grant-plan
{ "userId": "user_123", "planId": "plan_free" }
→ 200 { "ok": true, "planId": "plan_free", "grantsApplied": 3, "resetAt": "…" }

Safe to repeat: a user who already has a plan gets "alreadyEnrolled": true and nothing changes. Only free plans.

Subscription: paid plan from another provider

POST /api/v1/subscription

POST /api/v1/subscription
{ "eventId": "evt_1", "userId": "user_123", "planId": "plan_pro",
  "status": "active", "periodEnd": "2026-11-05T00:00:00Z" }
→ 200 { "ok": true, "source": "gateway", ... }

See other payment providers. The same eventId twice returns "alreadyApplied": true.

More endpoints

Less common

Endpoint	What it does
POST /api/v1/grant	Set one balance by hand: { userId, feature, balance, resetAt? }. Does not refill.
GET / PUT /api/v1/rules	Read or replace your plan table.
GET / PATCH /api/v1/billing	Stripe connection status (never returns secrets); PATCH saves the webhook secret or switches the provider.
POST /api/webhooks/stripe	Where Stripe sends events. See Connect Stripe.
GET /api/v1/health	Uptime check, no key needed.

Errors

Error bodies look like { "error": "Unknown feature \"x\". Add it to your plan table…", "code": "unknown_feature" }.

Status codes

Status	Means	What to do
200 with allowed: false	Not on the plan, or nothing left. A normal answer.	Block the action and offer an upgrade.
400 invalid_request	Missing or wrong fields. The message says which.	Fix the request.
401	Missing, wrong or revoked API key.	Check USAGEGATE_KEY, or create a new key.
402	Your own UsageGate plan has used its monthly quota (not your user's credits).	Upgrade in Dashboard → Billing.
404 unknown_feature	That feature key isn't in your plan table.	Add it in Access rules or fix the spelling.
409	You reported a subscription while Stripe is your payment provider.	Choose Other in Dashboard → Payment gateway.
429 / 503	Too many requests, or UsageGate briefly unavailable.	Retry. The SDK lets requests through by default.