Errors

When the API can't do what a request asks, it answers with a 4xx or 5xx status and an error object. The code is stable between versions, so your code can branch on it. The message is for people and can change.

A conversion that runs and then fails is different: the request succeeded, and the conversion ends with status: "failed" and the reason in error. See Failed conversions.

The error object#

Every error has the same shape:

{
    "error": {
        "code": "too_many_active",
        "message": "5 conversions are already queued or running on this account. Start this one when one of them ends.",
        "request_id": "req_01k7r3j9qf8m2v6x4t0c5n1h8d"
    }
}

When the request has missing or invalid fields, the code is invalid_request and fields lists the problems per field:

HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
    "error": {
        "code": "invalid_request",
        "message": "Some fields are missing or invalid.",
        "fields": {
            "spec": ["The spec field is required."]
        },
        "request_id": "req_01k7r3jb2c4e6g8j0m2p4r6t8v"
    }
}

Every answer, error or not, carries an X-Request-Id header. The TypeScript SDK throws errors as IntoSQLError with status, code, message, fields and requestId.

Error codes#

needs_pro, suspended, forbidden and unauthenticated are checked before anything else, on every endpoint.

Rate limits#

There are two limits:

• Requests: 120 a minute per API key. Each key has its own limit, so one script can't slow another key of the same account.
• Active conversions: five queued or running at once per account, across all its keys. Conversions waiting for their upload don't count.

Successful answers carry the request limit in headers:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117

Over the limit, the API answers 429 with rate_limited, with X-RateLimit-Remaining: 0 and a Retry-After header that says how many seconds to wait before the next request.

too_many_active also answers 429, with Retry-After: 30. A slot frees as soon as a running conversion ends, which a webhook tells you.

Idempotency#

Every POST (opening, starting and canceling a conversion, and sending a case) accepts an Idempotency-Key header, so a request you send again after a timeout or a lost connection runs only once. GET and DELETE ignore it: they are safe to repeat as they are.

POST /api/v1/conversions HTTP/1.1
Authorization: Bearer <key>
Content-Type: application/json
Idempotency-Key: import-ventas-2026-10-16

How the key works:

Details that matter:

• Keys belong to the account. Two keys of the same account share them.
• The body is compared byte for byte. Send the retry with exactly the same body. Serializing the same object again with keys in another order counts as a different request.
• Errors are kept too. A 4xx such as invalid_spec is replayed for the same key. After fixing the request, use a new key.
• 5xx answers aren't kept, so a retry with the same key after server_error runs again.

Use a random UUID per request, or a key tied to the work, such as import-<file>-<date>, so a retry after your process restarts reuses it.

Retry safely#

• Retry on a lost connection, a timeout, and the codes rate_limited, too_many_active, request_in_progress and server_error (any 5xx). Wait Retry-After seconds when the answer has it, otherwise double the wait between attempts, and send the same Idempotency-Key with each POST.
• Never retry already_started: the conversion is on its way, so read it instead. Don't retry unchanged on other 4xx codes either; they describe the request or the account, and sending it again gets the same answer.
• Reads and deletes (GET, DELETE) are safe to repeat as they are.
• The file upload to upload.url is a PUT to storage, outside the API. Repeating it replaces the file, which is safe before you start the conversion. The address works for an hour.

Every IntoSQL SDK does all of this: it adds a random Idempotency-Key to every POST, keeps it across retries, and retries lost connections and the codes above, twice by default.

Failed conversions#

Once a conversion is queued, problems with the file no longer come back as HTTP errors. The conversion ends with status: "failed", and error says why, with a stable code:

{
    "data": {
        "id": "01k7r3j9qf8m2v6x4t0c5n1h8d",
        "status": "failed",
        "error": {
            "code": "encrypted_file",
            "message": "\"ventas.xlsx\" is protected with a password.",
            "problems": []
        },
        "output": null,
        "finished_at": "2026-10-16T14:03:27+00:00"
    }
}

When the engine refuses the file, code is the engine's own: empty_file, corrupt_file, encrypted_file, unsupported_format, sheet_not_found, no_columns, or invalid_spec with the reasons in problems. Errors explains each one. The rest happen on our side:

A failed or canceled conversion doesn't count toward the month's allowance. The SDKs raise ConversionFailedError with the code and the message, and a webhook sends conversion.failed with the whole conversion in data.

If a file didn't convert well, or at all, send it to us: a failed conversion keeps its upload until it expires, so the case can carry the file.

Rows the engine rejects don't fail the conversion. They are counted in report.rows.rejected, with the reason for each in report.problems.