Status Codes

HTTP status codes returned by the API.

Success Codes

Code	Meaning
200 OK	Request successful
201 Created	Resource created

Error Codes

Code	Meaning
400 Bad Request	Invalid request data
401 Unauthorized	Missing or invalid API key
403 Forbidden	Key doesn't have permission
404 Not Found	Resource doesn't exist
409 Conflict	Resource already exists
422 Unprocessable Entity	Validation error
500 Internal Server Error	Server error

Error Response Format

{
  "detail": "Plan not found"
}

Common Errors

Authentication

{
  "detail": "Invalid API key"
}

→ Check your API key is correct and has the right permissions.

Validation

{
  "detail": "amount_sats must be greater than 0"
}

→ Check your request data matches the expected format.

Not Found

{
  "detail": "Subscription not found"
}

→ The resource ID doesn't exist or belongs to a different wallet.

Conflict

{
  "detail": "You already have an active subscription to this plan"
}

→ The subscriber already has an active subscription.

NWC Error Codes

Error codes returned by NWC (Nostr Wallet Connect) operations.

Validation Errors

These are returned when validating an NWC connection string:

Error Message	Cause
"Please provide a wallet connection string"	Empty NWC string
"Invalid connection string format..."	Doesn't start with nostr+walletconnect://
"Invalid wallet public key..."	Missing or malformed pubkey
"Invalid or missing secret..."	Missing or malformed secret
"Connection timed out..."	Wallet didn't respond
"Relay rejected the connection..."	HTTP 403 from relay

Payment Error Codes

These codes are returned in the error_code field when an NWC payment fails:

Code	Meaning	User Message
INSUFFICIENT_BALANCE	Wallet doesn't have enough sats	Your wallet doesn't have enough sats for this payment.
QUOTA_EXCEEDED	Spending limit reached	Your wallet's spending limit has been reached.
RATE_LIMITED	Too many requests	Too many payment requests. Please wait a moment.
UNAUTHORIZED	Connection revoked/expired	Wallet connection was revoked. Please reconnect.
PAYMENT_FAILED	Generic failure	Payment couldn't be completed.
TIMEOUT	No response in time	Your wallet didn't respond in time.
NO_RESPONSE	No response received	No response received from your wallet.
CONNECTION_ERROR	Relay connection failed	Could not connect to your wallet.
NOT_FOUND	Invoice not found/expired	Invoice not found or expired.
INTERNAL	Wallet internal error	Wallet encountered an internal error.
OTHER	Unknown error	Something went wrong with the payment.

Example NWC Error Response

{
  "subscription_id": "sub_xyz789",
  "status": "pending",
  "message": "Your wallet doesn't have enough sats for this payment.",
  "error_code": "INSUFFICIENT_BALANCE"
}