> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Create a balance block on an infraction report > Places an incremental balance block against an infraction report and relays the hold to the SPI Block Balancer. `amount` in the response is the amount Pix Lerian asks the SPI to hold: the requested amount, capped at the headroom left on the report and on the contested transaction across the reports that contest it. The SPI can hold less when the balance is short. `requestRef` identifies the block. A repeat of the same `requestRef` replays the block and answers `201` once the hold is confirmed. A new `requestRef` blocks the amount again. A `requestRef` can repeat across infraction reports. When the SPI refuses the hold on the first request with any status except `409`, Pix Lerian returns its error and keeps nothing, so you can retry with the same `requestRef`. When the SPI leaves the hold unanswered, the block stays `PENDING` without `spiBlockId`, because the SPI can already hold the funds: repeat the call with the same `requestRef`. A `409` from the SPI keeps the block `FAILED`: a hold of an earlier attempt can still stand, so do not send a new `requestRef`. The call answers `409` when the infraction is not in a blockable state, already has a block settling or settled, or has a refund operation in progress on a linked refund. The last case is temporary: retry with the same `requestRef` once the operation ends. It answers `422` (`PIX-0013`) when no headroom is left on the report or on the contested transaction. The report must belong to the authenticated organization, otherwise the call answers `404`. ## OpenAPI ````yaml /es/openapi/v3-current/pix-lerian-dict.yaml post /dict/infraction-reports/{id}/balance-blocks openapi: 3.1.0 info: contact: name: Lerian Studio url: https://lerian.studio description: >- Public API for Pix keys, claims, fraud markers, infraction reports, and MED funds recovery. license: name: Lerian Studio General License title: Pix Lerian — DICT version: 1.2.0 servers: - url: https://api.example.com/dict-hub/v1 description: >- Replace the example host with the URL provided during environment onboarding. security: - BearerAuth: [] tags: - description: Manage ownership and portability claims for Pix keys. name: Claims - description: Register, retrieve, list, update, and remove Pix keys. name: Entries - description: Create, query, list, and cancel DICT fraud markers. name: Fraud Markers - description: Manage participant-scoped MED 2.0 funds recoveries. name: Funds Recoveries - description: Manage MED 2.0 infraction reports for the authenticated organization. name: Infraction Reports - description: Look up Pix keys and check whether keys exist in the DICT directory. name: Keys - description: Create, query, cancel, and settle MED 2.0 refunds. name: Refunds - description: >- Read the state of key reconciliation against BACEN, and start a verification or a file reconciliation. name: VSync paths: /dict/infraction-reports/{id}/balance-blocks: post: tags: - Infraction Reports summary: Create a balance block on an infraction report description: >- Places an incremental balance block against an infraction report and relays the hold to the SPI Block Balancer. `amount` in the response is the amount Pix Lerian asks the SPI to hold: the requested amount, capped at the headroom left on the report and on the contested transaction across the reports that contest it. The SPI can hold less when the balance is short. `requestRef` identifies the block. A repeat of the same `requestRef` replays the block and answers `201` once the hold is confirmed. A new `requestRef` blocks the amount again. A `requestRef` can repeat across infraction reports. When the SPI refuses the hold on the first request with any status except `409`, Pix Lerian returns its error and keeps nothing, so you can retry with the same `requestRef`. When the SPI leaves the hold unanswered, the block stays `PENDING` without `spiBlockId`, because the SPI can already hold the funds: repeat the call with the same `requestRef`. A `409` from the SPI keeps the block `FAILED`: a hold of an earlier attempt can still stand, so do not send a new `requestRef`. The call answers `409` when the infraction is not in a blockable state, already has a block settling or settled, or has a refund operation in progress on a linked refund. The last case is temporary: retry with the same `requestRef` once the operation ends. It answers `422` (`PIX-0013`) when no headroom is left on the report or on the contested transaction. The report must belong to the authenticated organization, otherwise the call answers `404`. operationId: createInfractionReportBalanceBlock parameters: - description: >- REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Resending the same key and request within 1 hour returns the original response, its status included, with X-Idempotency-Replayed: true. Reusing the key with a divergent method, path or body, or while the first request runs, is PIX-0031 @ 412. in: header name: X-Idempotency required: true schema: maxLength: 64 minLength: 1 type: string - description: Infraction report internal ID (UUID format) in: path name: id required: true schema: description: Infraction report internal ID (UUID format) examples: - 018f8c1d-1234-7abc-9def-000000000001 type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateBalanceBlockRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/CreateBalanceBlockResponse' description: Created '400': content: application/json: example: code: PIX-0030 title: Idempotency Key Required message: >- The X-Idempotency header is required for this operation and must be within the accepted length. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- X-Idempotency absent or longer than 64 bytes (PIX-0030). Legacy {code,title,message} envelope, NOT problem+json. Route-guard refusals (PIX-0010) answer in the legacy {code,title,message} envelope too. '412': content: application/json: example: code: PIX-0031 title: Idempotency Key Conflict message: >- The X-Idempotency header is held by a request still running or whose receipt could not be stored, or was already used with a different request. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- Refused under this X-Idempotency (PIX-0031): the first request under it is still running (with Retry-After: 1), its receipt could not be stored and the key is held for the hour, or the request differs from the first (method, URL, body, or identity header among X-Account-Id / X-Reason / X-End-To-End-Id). An earlier request under this key may already have executed. Legacy {code,title,message} envelope, NOT problem+json. '415': content: application/json: example: code: PIX-0016 title: Unsupported Media Type message: >- The request body must be sent with Content-Type: application/json. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' description: >- The non-empty request body is missing an accepted JSON Content-Type (PIX-0016), answered in the legacy {code,title,message} envelope over application/json, NOT problem+json. '500': content: application/json: example: code: PIX-0000 title: Internal Server Error message: >- The server encountered an unexpected error. Please try again later. schema: $ref: '#/components/schemas/LegacyErrorEnvelope' application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error. default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error components: schemas: CreateBalanceBlockRequest: additionalProperties: false properties: amount: examples: - '1500.00' type: string requestRef: examples: - if-req-2026-07-15-0001 type: string required: - requestRef - amount type: object CreateBalanceBlockResponse: additionalProperties: false properties: amount: examples: - '1500.00' type: string attemptNumber: examples: - 1 format: int64 type: integer createdAt: examples: - '2026-07-15T13:30:00Z' format: date-time type: string id: examples: - 018f8c1d-1234-7abc-9def-000000000002 type: string spiBlockId: examples: - 018f8c1d-1234-7abc-9def-000000000099 type: string status: enum: - PENDING - SETTLING - SETTLED - RELEASED - FAILED examples: - PENDING type: string required: - id - spiBlockId - status - amount - attemptNumber - createdAt type: object LegacyErrorEnvelope: additionalProperties: false properties: code: description: PIX-XXXX error code type: string message: description: Human-readable error message type: string title: description: Short error title type: string fields: additionalProperties: type: string description: Per-field detail, keyed by the field or header the refusal names type: object headers: additionalProperties: type: string description: Per-header detail, keyed by the request header the refusal names type: object required: - code - title - message type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.