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) |
request_in_progress | 409 | Another request with this Idempotency-Key is still running; retry after Retry-After |
idempotency_key_reused | 409 | This Idempotency-Key was already used with a different request body |
gone | 410 | The resource existed and has been permanently removed |
payload_too_large | 413 | The request body (or an upload) exceeds the allowed size |
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) |
client_error | 4xx | A client-caused failure with no more specific code; the real status is on the HTTP response |
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.