API
Errors
Every non-2xx response follows a Stripe-shaped error envelope.
Every non-2xx response carries an error object:
{
"error": {
"type": "invalid_request_error",
"code": "code_in_use",
"message": "Account code 1010 is already in use.",
"param": "code"
}
}Error types
| HTTP | type | When |
|---|---|---|
| 400 | invalid_request_error | Bad input — missing field, wrong type, validation fail. |
| 401 | authentication_error | Missing, malformed, expired, or revoked API key. |
| 403 | permission_error | Key lacks the required scope. |
| 404 | not_found_error | Resource doesn't exist or isn't in your organization. |
| 409 | conflict_error | Uniqueness or state conflict (e.g. duplicate code). |
| 429 | rate_limit_error | Too many requests in a window. |
| 500 | api_error | Server-side bug. Reported automatically; please retry. |
Handling errors
- Switch on
typeandcode, notmessage. The message is for humans and may change. paramidentifies the offending field on 400s (for nested fields: dotted path, e.g.lines.0.debit).- Retry policy. 5xx errors are safe to retry with exponential backoff. 429s honor the rate-limit window. 4xx errors mean the request was bad — retrying won't help unless you change something.
Idempotency
Not yet supported. If a POST fails halfway with a 5xx, retrying with
the same payload could create a duplicate. Best practice for now: include
a unique reference on transactions and check for duplicates on the
server side, or use the API's read endpoints to verify state before
retrying. Native idempotency keys are on the roadmap.