HTTP status codes, error shape, rate-limit headers, and per-plan quotas.

Errors & Rate Limits

The recv API uses standard HTTP status codes and a single, consistent JSON error shape.

HTTP status codes

Code	Meaning
`200`	OK.
`201`	Created (e.g. a new invoice).
`204`	No content (successful action with no body).
`400`	Bad request — missing/invalid parameter, unsupported network, non-cancellable invoice, or simulating a non-test invoice.
`401`	Unauthorized — missing or invalid API key.
`403`	Forbidden — plan does not include the API, missing scope, blocked workspace, or simulating with a live key.
`404`	Not found — the resource doesn't exist in your workspace.
`409`	Conflict — an `Idempotency-Key` was reused with a different body, or the original request is still processing.
`429`	Too many requests — minute rate limit or monthly quota exceeded.
`500`	Internal server error.

Error response body

Every error returns a JSON object with a single error field:

{ "error": "invalid API key" }

For security, 5xx responses return a generic {"error": "internal server error"} while the detail is logged server-side. 4xx responses surface the specific, request-shaped message (validation, auth, conflict), for example:

missing API key
invalid API key
API key scope invoices:write is required
current plan does not include recv Developer or recv Business API access
invalid base_amount_usd
only workspace-created invoices can be canceled
payment simulator is only available for test_ API keys
minute rate limit exceeded / monthly API quota exceeded

Rate-limit headers

Every authenticated /v1 response includes the current minute budget, and monthly budget where the plan has a cap:

Header	Description
`X-RateLimit-Limit-Minute`	Requests allowed per minute on your plan.
`X-RateLimit-Remaining-Minute`	Requests left in the current minute window.
`X-RateLimit-Limit-Month`	Monthly request cap (when set).
`X-RateLimit-Remaining-Month`	Requests left this calendar month (UTC).

Exceeding the minute limit or the monthly cap returns 429.

Per-plan quotas

API limits and webhook retry budgets are set by your workspace's active plan. The Merchant and Trial plans do not include API access.

Plan	Rate limit	Monthly request cap	Active API keys	Webhook retries
Developer	90 req/min	50,000	3	3
Business	300 req/min	200,000	10	5

Handling errors (Python)

import requests

resp = requests.get(
    "https://recv.money/v1/invoices/999999",
    headers={"X-API-Key": "YOUR_KEY"},
)

if resp.status_code == 404:
    print("Invoice not found.")
elif resp.status_code == 429:
    print("Rate/quota exceeded. Remaining this minute:",
          resp.headers.get("X-RateLimit-Remaining-Minute"))
elif not resp.ok:
    print("Error:", resp.json().get("error"))

← PreviousWebhooks Next →Mcp

Ready to accept crypto payments?

Launch Console Networks