> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fincle.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# API conventions

> Message format, idempotency, pagination, limits and error handling.

This page consolidates the rules applicable to all operations of the API.

## Protocol and format

Requests and responses are exchanged over HTTPS, in JSON (RFC 8259) encoded in UTF-8. Requests with a body must send the `Content-Type: application/json` header.

| Quantity | Representation |
| - | - |
| Monetary amount | Integer, in cents of Brazilian real (BRL, ISO 4217). The amount of R\$ 1,250.00 is represented by `125000`. |
| Fee percentage | Integer, in hundredths of a percent. The percentage of 2.99% is represented by `299`. |
| Date and time | Text in ISO 8601 format, in UTC. Example: `2026-11-12T14:10:17.000Z`. |
| Date | Text in `YYYY-MM-DD` format. |
| Document | CPF or CNPJ, accompanied by its type in `documentType` (`cpf` or `cnpj`). |

## Response envelope

Successful responses contain `success: true` and, when there is content, the `data` field. Failure responses adopt a single envelope, in which the `message` field describes the cause.

```json theme={null}
{
  "success": false,
  "message": "Documento inválido para o tipo selecionado"
}
```

The text of the `message` field is returned in Portuguese. Integrations must base their logic on the HTTP status and, where present, on the `code` field, and not on the message text.

## Idempotency

Idempotency ensures that repeating a request, as a result of a network failure or a timeout, does not produce a duplicate financial effect.

In Pix, card and subscription charge operations, the idempotency key is sent in the `Idempotency-Key` header. Repeating the request with the same key returns the transaction already recorded.

```bash theme={null}
curl -X POST https://api.fincle.com.br/card \
  -H "Authorization: Bearer $FINCLE_TOKEN" \
  -H "Idempotency-Key: 7c1f0b9e-3a52-4d6c-9e1b-5f2a8c4d7e10" \
  -H "Content-Type: application/json" \
  -d '{ "amountInCents": 125000, "card": { "cardToken": "tok_9f2c1a7b4d6e" }, "customer": { "documentType": "cpf", "document": "31845792041" } }'
```

In the transfer operation, the key is sent in the body, in the `idempotencyKey` field of `POST /transfers`, and is mandatory.

It is recommended to generate a universally unique identifier (UUID) for each payment intent and to reuse it in every retry of the same intent.

## Pagination

Listing operations accept the `page` parameter, starting at 1, and the `pageSize` parameter, limited to 100 records. The response contains the records in `data` and the totals in `pagination`.

```json theme={null}
{
  "success": true,
  "data": [],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 0,
    "totalPages": 0
  }
}
```

Two operations are exceptions. `GET /transactions` paginates by offset, through the `offset` parameter, and reports the total number of records in `totalRows`. `GET /subscriptions` uses the `limit` parameter in place of `pageSize`.

## Rate limit

Up to 1000 requests per minute are allowed per source IP address. Every response reports the state of the limit in the headers below.

| Header | Description |
| - | - |
| `x-ratelimit-limit` | Maximum number of requests in the window. |
| `x-ratelimit-remaining` | Requests remaining in the current window. |
| `x-ratelimit-reset` | Time, in seconds, until the window resets. |

When the limit is exceeded, the response is `429`, accompanied by the `retry-after` header, which states the waiting time, in seconds, before a new request.

## Response codes

| Code | Meaning |
| - | - |
| `200` | Request processed successfully. In card charges, the outcome of the authorization is given in the body. |
| `201` | Resource created. |
| `400` | Request rejected by a business rule. In charge operations, it also covers validation failures. |
| `401` | Access token missing, invalid or expired. |
| `403` | Operation not permitted for the account. |
| `404` | Resource nonexistent or belonging to another account. |
| `422` | Request not in conformity with the validation schema. |
| `429` | Rate limit exceeded or, in card charges, payer temporarily blocked. |
| `500` | Internal failure. The request may be repeated, provided the idempotency key is preserved. |

## Retry policy

Network failures and `5xx` responses may be retried, provided the idempotency key is preserved. `4xx` responses indicate a condition that does not change with mere repetition and require correction of the request, with the exception of the `429` response, which must be repeated after the interval stated in `retry-after`. Increasing intervals between retries are recommended.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.