Home · Auth, errors & idempotency
Conventions
Auth, errors & idempotency
The conventions that apply across the whole Florentin API — understood once, they apply everywhere.
Learn once, apply everywhere
The Florentin API is deliberately uniform: authentication, response shape, error format and retryability work the same across all endpoints. That makes integration predictable and reduces errors — whether you create customers, record usage or manage webhooks.
At a glance
✓
AuthBearer 42|<secret>, bound to the provider domain.
✓
Base/api/v1, one REST API per domain.
✓
Response{ data, meta } on success.
✓
Errors{ error: { message, … } } with HTTP status.
✓
Idempotencyidempotency_key on billing mutations.
✓
Deduperequest_id on /credits/consume.
Error format
← 422 Unprocessable Entity
{ "error": { "message": "email is required" } }
← 401 Unauthorized
{ "error": { "message": "invalid or missing bearer token" } }FAQ
Frequently asked
How are tokens structured?
As <id>|<secret>, e.g. 42|kP3f9c… — stored hashed on the server.
What is idempotency for?
So a retried billing mutation doesn't apply twice; on /credits/consume, request_id serves the same purpose.
Build your product. We'll handle the rest.
Accounts, billing, credits, portal, access — integrated. Stripe fully included.
Start free →