API
Errors
The v1 error envelope, HTTP status codes, and request-id correlation.
Every error response has the same shape:
{
"error": {
"code": "invalid_request",
"message": "Required field 'name' is missing",
"requestId": "req_a1b2c3d4e5f6",
"details": { "field": "name" }
}
}| Code | Status | Meaning |
|---|---|---|
unauthorized | 401 | Missing or invalid credentials |
forbidden | 403 | Authenticated, but lacks the required scope or organization |
not_found | 404 | Resource does not exist or is in another organization |
invalid_request | 400 | Body or query parameters failed validation |
conflict | 409 | Resource state prevents the operation (e.g. deleting a sent invoice; rotating an idempotency key with a different body) |
rate_limited | 429 | Too many requests for this key; see Retry-After header |
method_not_allowed | 405 | Operation not supported on this resource (e.g. payouts are read-only) |
internal_error | 500 | Server-side failure; the request id is your friend when contacting support |
Cross-organization isolation
Resources scoped to organizations return 404 not_found (not 403) when accessed from another organization. This prevents leaking the existence of resources you don't have access to.
Request IDs
Every response includes requestId inside the error envelope (for errors). Successful responses do not need it for correlation. Include the request id when reporting issues.