Back to API documentation

ValidConvert API error catalog

Machine-readable errors use application/problem+json. The type URI points to the matching anchor on this page. Details are intentionally sanitized and never contain financial document content, secrets, SQL, or internal filesystem paths.

`VC_AMBIGUOUS_AUTHENTICATION`

HTTP status: 400
Retryable: No
Meaning: Both session and Bearer authentication were supplied where exactly one is allowed.
Client action: Send either the web session or the API key, not both.

`VC_AUTHENTICATION_METHOD_NOT_ALLOWED`

HTTP status: 400
Retryable: No
Meaning: The endpoint does not accept the authentication method used.
Client action: Use the authentication method documented for the endpoint.

`VC_EMPTY_FILE`

HTTP status: 400
Retryable: No
Meaning: The conversion request body is empty.
Client action: Send a non-empty financial file.

`VC_IDEMPOTENCY_KEY_INVALID`

HTTP status: 400
Retryable: No
Meaning: The Idempotency-Key is not a canonical lowercase UUIDv4.
Client action: Generate a new canonical lowercase UUIDv4.

`VC_IDEMPOTENCY_KEY_REQUIRED`

HTTP status: 400
Retryable: No
Meaning: An operation requiring idempotency was sent without a valid Idempotency-Key.
Client action: Send the required Idempotency-Key header.

`VC_INPUT_SIZE_MISMATCH`

HTTP status: 400
Retryable: No
Meaning: X-ValidConvert-Input-Bytes does not match the bytes actually received.
Client action: Send the exact decimal byte count and retry with the same logical request semantics.

`VC_INVALID_CLIENT_REQUEST_ID`

HTTP status: 400
Retryable: No
Meaning: X-Client-Request-Id is invalid.
Client action: Use a canonical UUIDv4 or omit the optional header.

`VC_INVALID_OR_EXPIRED_TOKEN`

HTTP status: 400
Retryable: No
Meaning: An email-verification or password-reset token is invalid, expired, revoked, or already used.
Client action: Request a fresh token when the relevant flow permits it.

`VC_INVALID_REQUEST`

HTTP status: 400
Retryable: No
Meaning: The request syntax, JSON body, parameters, or billing/webhook request is invalid.
Client action: Correct the request according to the API contract.

`VC_UNSUPPORTED_CONVERSION`

HTTP status: 400
Retryable: No
Meaning: The requested source/target conversion is not supported by the invoked surface.
Client action: Use a converter advertised by the converter catalog.

`VC_AUTHENTICATION_REQUIRED`

HTTP status: 401
Retryable: No
Meaning: Authentication is required.
Client action: Authenticate with the method documented for the endpoint.

`VC_INVALID_API_KEY`

HTTP status: 401
Retryable: No
Meaning: The Bearer API key is malformed, unknown, revoked, or expired.
Client action: Use the currently active API key.

`VC_INVALID_CREDENTIALS`

HTTP status: 401
Retryable: No
Meaning: Login credentials are invalid.
Client action: Check the credentials and retry; the response does not reveal whether the account exists.

`VC_INSUFFICIENT_CREDITS`

HTTP status: 402
Retryable: No
Meaning: The account does not have enough available credits.
Client action: Purchase credits or wait for reserved credits to be released, then retry.

`VC_ACCOUNT_RESTRICTED`

HTTP status: 403
Retryable: No
Meaning: The account is restricted or under billing review for this operation.
Client action: Resolve the account restriction before retrying the blocked operation.

`VC_API_PURCHASE_REQUIRED`

HTTP status: 403
Retryable: No
Meaning: API eligibility requires at least one economically valid historical purchase.
Client action: Complete a valid purchase before creating/using API access for conversions.

`VC_CSRF_INVALID`

HTTP status: 403
Retryable: No
Meaning: The CSRF token is missing or invalid.
Client action: Fetch /v1/auth/csrf in the same browser session and send X-CSRF-TOKEN.

`VC_EMAIL_NOT_VERIFIED`

HTTP status: 403
Retryable: No
Meaning: Verified email is required for this operation.
Client action: Complete email verification and retry.

`VC_FORBIDDEN`

HTTP status: 403
Retryable: No
Meaning: The authenticated principal is not allowed to perform the operation.
Client action: Do not retry unless the account/authentication state changes.

`VC_ORIGIN_FORBIDDEN`

HTTP status: 403
Retryable: No
Meaning: The browser Origin is not permitted for the protected web operation.
Client action: Use the canonical ValidConvert web origin.

`VC_REAUTHENTICATION_REQUIRED`

HTTP status: 403
Retryable: No
Meaning: Recent authentication is required.
Client action: Reauthenticate and retry within the recent-authentication window.

`VC_TRIAL_EXHAUSTED`

HTTP status: 403
Retryable: No
Meaning: The account has exhausted its lifetime successful trial allowance.
Client action: Use a paid conversion.

`VC_TURNSTILE_INVALID`

HTTP status: 403
Retryable: Yes
Meaning: The Turnstile token is invalid, expired, reused, or does not match the expected hostname/action.
Client action: Obtain a fresh Turnstile token for the documented action and retry.

`VC_TURNSTILE_REQUIRED`

HTTP status: 403
Retryable: Yes
Meaning: A Turnstile challenge is required for this request.
Client action: Complete the required Turnstile action and retry with a fresh token.

`VC_CONVERTER_NOT_FOUND`

HTTP status: 404
Retryable: No
Meaning: The requested converter_id does not exist.
Client action: Use converter_id=camt053-to-mt940 for the current V1 converter.

`VC_NOT_FOUND`

HTTP status: 404
Retryable: No
Meaning: The requested resource is missing or not visible to this account.
Client action: Check the opaque identifier/path; do not infer ownership from this response.

`VC_METHOD_NOT_ALLOWED`

HTTP status: 405
Retryable: No
Meaning: The HTTP method is not supported for the route.
Client action: Use the method documented by OpenAPI.

`VC_NOT_ACCEPTABLE`

HTTP status: 406
Retryable: No
Meaning: The requested response media type is not supported.
Client action: Accept application/octet-stream for conversion success responses.

`VC_UPLOAD_TIMEOUT`

HTTP status: 408
Retryable: Yes
Meaning: The application upload deadline was exceeded while receiving the input.
Client action: Retry the upload. Exact transport-level socket cutoff is an infrastructure concern and is not guaranteed by the Java application alone.

`VC_API_KEY_ALREADY_EXISTS`

HTTP status: 409
Retryable: No
Meaning: An active API key already exists for the account.
Client action: Use rotate instead of create when replacing an existing key.

`VC_API_KEY_SECRET_ALREADY_ISSUED`

HTTP status: 409
Retryable: No
Meaning: The one-time API key secret was already issued for this idempotent operation.
Client action: Do not attempt to recover the old secret; rotate/create a new key through a new valid operation.

`VC_IDEMPOTENCY_IN_PROGRESS`

HTTP status: 409
Retryable: Yes
Meaning: The idempotent operation is still processing.
Client action: Honor Retry-After and retry with the same key and identical logical request.

`VC_IDEMPOTENCY_EXPIRED`

HTTP status: 410
Retryable: No
Meaning: The retained idempotent conversion result has expired.
Client action: Use a new Idempotency-Key for a new operation.

`VC_RESULT_LOST`

HTTP status: 410
Retryable: No
Meaning: A result expected to be retained was unexpectedly lost.
Client action: The backend compensates the economic effect exactly once; submit a new operation if needed.

`VC_PRECONDITION_FAILED`

HTTP status: 412
Retryable: No
Meaning: If-Match references an API-key representation that is no longer current.
Client action: GET the current API-key metadata/ETag and retry deliberately.

`VC_FILE_TOO_LARGE`

HTTP status: 413
Retryable: No
Meaning: The input exceeds the applicable byte limit.
Client action: Reduce the file size or use the correct paid/trial surface.

`VC_UNSUPPORTED_CONTENT_ENCODING`

HTTP status: 415
Retryable: No
Meaning: Compressed HTTP request bodies are not supported.
Client action: Send an uncompressed application/octet-stream body.

`VC_UNSUPPORTED_MEDIA_TYPE`

HTTP status: 415
Retryable: No
Meaning: The conversion Content-Type is not application/octet-stream.
Client action: Send Content-Type: application/octet-stream.

`VC_IDEMPOTENCY_CONFLICT`

HTTP status: 422
Retryable: No
Meaning: The Idempotency-Key was already used for a different logical request.
Client action: Use the original request or a new key for a new operation.

`VC_INVALID_FILE`

HTTP status: 422
Retryable: No
Meaning: The financial file cannot be converted safely.
Client action: Correct the input document and submit a new logical operation.

`VC_OUTPUT_LIMIT_EXCEEDED`

HTTP status: 422
Retryable: No
Meaning: The generated output would exceed the output-size limit.
Client action: Reduce/split the input before submitting a new operation.

`VC_TOO_MANY_TRANSACTIONS`

HTTP status: 422
Retryable: No
Meaning: The input contains more transactions than the applicable limit.
Client action: Reduce/split the input before submitting a new operation.

`VC_UNSUPPORTED_CONVERTER_VERSION`

HTTP status: 422
Retryable: No
Meaning: The requested converter version is not supported.
Client action: Use converter_version=1 for the current V1 converter.

`VC_UNSUPPORTED_FORMAT`

HTTP status: 422
Retryable: No
Meaning: The input format or CAMT version is not supported.
Client action: Use supported CAMT.053.001.02 through .14 input.

`VC_PRECONDITION_REQUIRED`

HTTP status: 428
Retryable: No
Meaning: If-Match is required for this API-key mutation.
Client action: GET API-key metadata and send the returned ETag as If-Match.

`VC_API_DAILY_CREDIT_LIMIT`

HTTP status: 429
Retryable: Yes
Meaning: The rolling 24-hour API credit budget is exhausted.
Client action: Retry after credits leave the rolling window.

`VC_CONCURRENCY_LIMIT`

HTTP status: 429
Retryable: Yes
Meaning: The account has reached its per-account conversion concurrency limit.
Client action: Retry after an active conversion finishes.

`VC_RATE_LIMIT`

HTTP status: 429
Retryable: Yes
Meaning: An HTTP abuse-protection rate limit was exceeded.
Client action: Honor Retry-After. The Problem response includes a sanitized limit_scope.

`VC_TRIAL_ATTEMPT_LIMIT`

HTTP status: 429
Retryable: Yes
Meaning: The account reached the rolling 24-hour trial-attempt limit.
Client action: Retry after attempts leave the rolling window or use paid conversion.

`VC_INTERNAL_ERROR`

HTTP status: 500
Retryable: No
Meaning: An unexpected internal error occurred and details were intentionally sanitized.
Client action: Retry only if appropriate for the surrounding operation; contact support with request_id if persistent.

`VC_CHECKOUT_PENDING`

HTTP status: 503
Retryable: Yes
Meaning: Checkout creation has an uncertain outcome and is being reconciled.
Client action: Honor Retry-After and retry with the same Idempotency-Key.

`VC_CONVERSION_TIMEOUT`

HTTP status: 503
Retryable: Yes
Meaning: Conversion processing exceeded the application processing deadline.
Client action: Retry according to the idempotency state returned by the service.

`VC_OPERATION_STATUS_UNKNOWN`

HTTP status: 503
Retryable: Yes
Meaning: The backend cannot safely determine the operation outcome.
Client action: Do not start a second logical operation blindly; retry/reconcile the same operation.

`VC_RESULT_TEMPORARILY_UNAVAILABLE`

HTTP status: 503
Retryable: Yes
Meaning: A retained result is temporarily unavailable.
Client action: Retry the same retrieval/replay later.

`VC_SERVICE_UNAVAILABLE`

HTTP status: 503
Retryable: Yes
Meaning: A required service, capacity slot, Turnstile verification, billing dependency, or storage function is temporarily unavailable.
Client action: Retry later while preserving idempotency where applicable.

`VC_TEMPORARY_STORAGE_FULL`

HTTP status: 503
Retryable: Yes
Meaning: Temporary encrypted conversion storage is full.
Client action: Retry later; do not change the logical request solely because of this error.