Errors

These rules apply to every Financy endpoint — payments, connections,
accounts, transactions, providers, and merchants alike. Every failed request
returns a standard HTTP status code and a JSON body in this shape:

{
  "type": "CLIENT_ERROR",
  "message": "Payment ID is not valid"
}

⚠️

Don't confuse these with payment statuses. An HTTP error means the

request failed. A payment that is rejected by the bank still returns
HTTP 200 with a payment status of RJCT — see Payment Status.

HTTP status codes

400 — Bad request

The most common failure. type is usually CLIENT_ERROR or VALIDATION_ERROR
(and PROVIDER_UNAVAILABLE when a bank is temporarily down). Representative
messages:

{ "type": "CLIENT_ERROR",    "message": "[\"paymentInformation is required\"]" }
{ "type": "VALIDATION_ERROR","message": "Merchant Id or creditor info is required" }
{ "type": "CLIENT_ERROR",    "message": "Redirect url is not in allowed url list" }
{ "type": "CLIENT_ERROR",    "message": "Creditor and debtor accounts are the same" }
{ "type": "CLIENT_ERROR",    "message": "Payment ID is not valid" }
{ "type": "CLIENT_ERROR",    "message": "Invalid provider" }
{ "type": "PROVIDER_UNAVAILABLE", "message": "The required provider is unavailable at this moment, Please contact us for more info" }
{ "type": "CLIENT_ERROR",    "message": "Production access is not enabled for this organization, you must include fake providers or contact us" }

💡

That last one is the sandbox gate: until production access is enabled,

payments must target sandbox providers. Use sandbox providers to test, and
contact us to enable production.

401 — Unauthorized

{ "message": "Unauthorized" }

The access token is missing, malformed, or expired. Request a fresh token from
POST /oauth/token (see Authentication) and retry. Tokens are per user, so
make sure you're sending the token for the right userId.

403 — Forbidden

The token is valid but lacks the permission for this action — for example
calling an endpoint your API key's plan/scopes don't include. There's no body;
the status alone signals it. If you believe you should have access, contact us.

404 — Not found

The route or the referenced entity doesn't exist. type is CLIENT_ERROR:

{ "type": "CLIENT_ERROR", "message": "Payment not found with this id" }
{ "type": "CLIENT_ERROR", "message": "Merchant not found in db" }
{ "type": "CLIENT_ERROR", "message": "Provider is not allowed for this payment" }

423 — Locked

Returned when deleting a Connection that can't be removed yet:

This connection is locked and can't be deleted currently. If you have BigQuery
enabled, you can only delete connections that were created at least 90 minutes ago.

Wait until the lock clears (at least 90 minutes after creation) and retry.

500 — Internal server error

Something failed on our side or at the provider. type is typically
INTERNAL_ERROR:

{ "type": "INTERNAL_ERROR", "message": "An unexpected server error has occurred" }
{ "type": "INTERNAL_ERROR", "message": "PROVIDER_ERROR" }

Retry with exponential backoff. If it keeps happening, contact us with the
message and the time of the request.

Error types

The type field takes one of:

Handling checklist

• 401 → refresh the token, retry once.
• 403 → the key can't do this; don't retry — fix scope/plan or contact us.
• 400 / 404 → fix the request; retrying unchanged won't help.
• 423 → wait, then retry.
• 500 / PROVIDER_UNAVAILABLE → retry with backoff; escalate if persistent.
• A 2xx with a failed payment status (RJCT / CANC / ERROR) is a
  payment outcome, not a transport error — handle it per Payment Status.