Errors and limits

Error responses use JSON even when the request omits Accept: application/json.

HTTP errors

Status	Meaning	Action
`401`	Missing, invalid, or revoked token.	Check the token and `Authorization` header.
`403`	Insufficient permissions or an operation unavailable to the company.	Check the token’s permissions and whether the operation is available.
`404`	The requested record or endpoint does not exist.	Check the URL, ID, and company assigned to the token.
`422`	Invalid data or an idempotency conflict.	Correct the request using the response details.
`429`	Request limit exceeded.	Wait as instructed by `Retry-After`.
`500`	Internal error.	Follow the retry rules below.
`503`	Service temporarily unavailable.	Wait, then follow the retry rules below.

Validation errors

A 422 response lists field errors in the errors object. Illustrative response when creating an invoice without a configured primary bank account:

{
  "message": "The given data was invalid.",
  "errors": {
    "bankAccountId": [
      "Company has no primary bank account configured."
    ]
  }
}

Set a primary bank account or send the bankAccountId of an existing company account. Each endpoint documents its validation rules.

Request limit

The default limit is 120 requests per minute per company. All tokens belonging to the company share it.

Response header	Meaning
`X-RateLimit-Limit`	The company’s limit.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`Retry-After`	On `429`: seconds to wait before the next attempt.
`X-RateLimit-Reset`	On `429`: Unix timestamp when the limit resets.

The first two headers also appear on successful responses. Contact info@fintoro.sk if you need a higher limit.

Idempotency

When creating records, send an Idempotency-Key header on supported endpoints:

Idempotency-Key: client-import-001

Choose a new key for each new record creation. When retrying the same request after a network error, keep both the key and body unchanged. While the original response is stored, the API returns it without creating another record. Keys are scoped to the company and endpoint. The response header Idempotency-Status is Original on the first request and Repeated when returning a stored response. Reusing a key with a different body returns 422:

{
  "error": "Idempotency-Key reused with different request payload"
}

Endpoints that support Idempotency-Key list it among their parameters. Idempotency does not replace your own mapping between records in your system and Fintoro.

Retrying requests

You can retry reads after a temporary error. Increase the wait between attempts; on 429, respect Retry-After. When creating a record, a timeout may mean the write succeeded but the response did not reach you. On a supported endpoint, retry with the original Idempotency-Key and unchanged body. Without a key, first check whether the record was created. Take the same care with 500 and 503 responses.

Diagnostics

Log the response’s X-Request-Id in your integration. When contacting support, include it along with the request time and endpoint.

Getting started

Using the API

Webhooks

Examples