Skip to main content

​
Errors and limits

Errors use a stable JSON shape: 
{
  "error": {
    "code": "invalid_subscription",
    "message": "Invalid option",
    "field": "period",
    "suggestedFix": "Use one of the supported billing periods: monthly, yearly, custom.",
    "allowedValues": ["monthly", "yearly", "custom"]
  },
  "requestId": "request-..."
}
field, suggestedFix, allowedValues, and writableFields are included when the server can provide a precise recovery hint. AI agents should use those fields to correct the payload instead of guessing.

​
Common error codes

StatusCodeMeaning
400invalid_jsonRequest body is not a JSON object
400invalid_subscriptionSubscription fields failed validation
400invalid_subscription_fieldThe request tried to write a server-managed field
400invalid_subscription_idSubscription ID is not a valid UUID
400invalid_paginationlimit or offset query parameter is out of range
400invalid_queryA filter or sort query parameter is invalid
400empty_patchPATCH body did not include any writable fields
401authentication_requiredMissing Bearer token
401invalid_api_keyAPI key is invalid or revoked
403insufficient_scopeThe API key lacks the write scope required for this operation
404subscription_not_foundSubscription does not exist for the API key owner
405method_not_allowedHTTP method is not supported
429rate_limit_exceededUser request limit or invalid-auth limit exceeded
500internal_errorUnexpected server error

​
Recovery fields

FieldMeaning
fieldThe request field that caused the error
suggestedFixHuman- and AI-readable correction guidance
allowedValuesValid enum values for fields such as currency or period
writableFieldsFields accepted by POST and PATCH subscription requests
Example non-writable field error: 
{
  "error": {
    "code": "invalid_subscription_field",
    "message": "Field is not writable: nextPaymentDate",
    "field": "nextPaymentDate",
    "suggestedFix": "Remove server-managed fields such as id, nextPaymentDate, createdAt, and updatedAt before retrying.",
    "writableFields": [
      "amount",
      "category",
      "currency",
      "customDate",
      "lastPaymentDate",
      "name",
      "notificationEnabled",
      "period",
      "status"
    ]
  },
  "requestId": "request-..."
}

​
Scopes

API keys carry scopes. A read key can list and read subscriptions and call the analytics and audit endpoints. A write key additionally allows create, update, cancel, pause, resume, and delete. A write call made with a read-only key returns 403 insufficient_scope; do not retry — request a write-scoped key. See Authentication.

​
Rate-limit headers

Authenticated API responses include: 
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
X-RateLimit-Reset is a Unix timestamp in seconds. Validation failures (400) are rejected before the hourly quota is consumed, so they do not count against your limit and do not carry rate-limit headers. Fixing the payload and retrying is free. 429 responses also include a Retry-After header with the number of seconds to wait before retrying. This applies both to the per-user request limit and to the “too many invalid API key attempts” lockout. 
Retry-After: 2700

​
CORS

The subscription API supports browser preflight requests: 
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS
Keep API keys out of browser apps unless you fully trust the browser context. CORS support is mainly for developer tooling, internal dashboards, or trusted local workflows.