Error response format
Every error response has the same shape:| Field | Type | Description |
|---|---|---|
error | string | Short error category matching the HTTP status (e.g. Bad Request, Unauthorized) |
message | string | Human-readable description of what went wrong |
HTTP status codes
400 Bad Request
The request body failed validation.
| Message | Cause |
|---|---|
Amount must be greater than 0 | amount is zero, negative, or not a valid decimal string |
Currency is required | currency is missing or empty |
Expires in minutes must be greater than 0 | expiresInMinutes is zero or negative |
Invalid webhook URL format | webhookUrl is not a valid URL |
Webhook URL must use HTTPS in production | webhookUrl uses HTTP in a production environment |
Webhook URL cannot point to localhost or loopback addresses | webhookUrl resolves to 127.0.0.1, ::1, or similar |
Webhook URL cannot point to private or internal IP addresses | webhookUrl resolves to a private IP range |
401 Unauthorized
Authentication failed. Check your API key.
| Message | Cause |
|---|---|
Missing or invalid Authorization header. Use: Bearer <api_key> | The Authorization header is absent or not in Bearer <key> format |
Invalid API key | The key was not found — it may have been deleted |
API key has been revoked | The key exists but has been explicitly revoked |
API key has expired | The key passed its expiry date |
403 Forbidden
The request was authenticated but not permitted.
| Message | Cause |
|---|---|
Merchant account is not active | Your account is suspended or pending review |
API key does not have the required permission: <permission> | The API key lacks the permission needed for this endpoint. See API key permissions |
404 Not Found
The requested resource does not exist under your account.
| Message | Cause |
|---|---|
Invoice not found | No invoice with that ID exists, or it belongs to a different merchant |
429 Too Many Requests
You have exceeded the rate limit for your account tier.
retryAfter field tells you how many seconds to wait before retrying. The response also includes rate limit headers:
| Tier | Read | Write |
|---|---|---|
| Free | 60 / min | 30 / min |
| Pro | 300 / min | 150 / min |
500 Internal Server Error
An unexpected error occurred on our side. These are rare and transient — retry with exponential backoff. If the issue persists, contact support.
API key permissions
When you create an API key in the dashboard, you can scope it to specific permissions. If a request is made with a key that lacks the required permission, you will receive:| Permission | Endpoints |
|---|---|
invoices:read | GET /api/v1/invoices/:id |
invoices:write | POST /api/v1/invoices |