Errors & limits

Errors have a stable structure and request identifier for diagnosis, without exposing raw provider data.

{
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "This key was used with different request fields.",
    "requestId": "req-42"
  }
}

Main codes

HTTP	Code	Action
400	`INVALID_REQUEST`	Fix format and unknown fields
400	`INVALID_DOCUMENT`	Review CPF/CNPJ
401	`UNAUTHORIZED` / `CHECKOUT_EXPIRED`	Renew credential or session
403	`INSUFFICIENT_SCOPE`	Use the required scope
403	`CHECKOUT_POLICY`	Check origin and network
403	`LIVE_SETTLEMENT_DISABLED`	Production is not enabled
404	`NOT_FOUND`	Missing resource or wrong workspace
409	`IDEMPOTENCY_CONFLICT` / `CHECKOUT_USED`	Retrieve the existing operation
429	`RATE_LIMITED`	Wait before retrying
503	`QUOTE_UNAVAILABLE` / `API_UNAVAILABLE`	Retry later without expired prices

Current limits

JSON body: 16 KiB. General protection: 180 requests/minute per IP observed by the API. Per key: 120 requests/minute. Public preview: 30 sessions/hour. Workspace creation: 3/day per account. Lists: up to 100 items.

These are initial parameters, not an SLA. Configure proxy trust, retention, pagination, and plan quotas before commercial scale.

Ambiguous outcomes

If the provider cannot confirm a request, never create another charge automatically. Reconcile the same operation. Currently this cannot move money because live creation is disabled.