Error catalog | Fincore

Fincore endpoints return gRPC-transcoded error payloads. The shared format for all Monato products is in Error format. This page covers Fincore specifics.

Error structure

Error response

{
  "code": 9,
  "message": "API Error",
  "details": [
    {
      "reason": "FAILED_PRECONDITION",
      "domain": "CORE",
      "metadata": {
        "error_detail": "The account does not have sufficient funds.",
        "http_code": "400",
        "error_code": "10-E4120"
      }
    }
  ]
}

Field	Description
`code`	gRPC status code mapped to HTTP.
`message`	General error message.
`details[].reason`	Machine-readable error category.
`details[].domain`	Service domain that produced the error, for example `CORE`.
`details[].metadata.error_detail`	Human-readable detail. Usually the most useful value for troubleshooting.
`details[].metadata.http_code`	HTTP status code, as a string.
`details[].metadata.error_code`	Optional internal error catalog code, when available.

Reason to HTTP status

The HTTP status is derived from details[].reason. Branch your handling on reason, not on the numeric suffix of error_code: a code ending in 4120 still returns 400.

`reason`	HTTP	Meaning
`FAILED_PRECONDITION`	`400`	A business rule blocked the operation, for example insufficient funds or a state that does not allow the transition.
`DATA_ERROR`	`400`	A field value is invalid for its type or format.
`MISSING_REQUIRED_FIELDS`	`400`	A required field is absent.
`VALUE_TOO_LONG`	`400`	A field exceeds its maximum length.
`UNIQUE_VIOLATION`	`409`	The resource already exists. In public flows this is the idempotency conflict.
`UNAUTHORIZED`	`401`	Missing, invalid, expired or environment-mismatched credentials.
`FORBIDDEN`	`403`	The client is not allowed to perform the operation.
`RESOURCE_NOT_FOUND`	`404`	The referenced resource does not exist for this client.
`INTERNAL`	`500`	Unexpected server or downstream error.

The API contract’s reason enum is DATA_ERROR, FAILED_PRECONDITION, MISSING_REQUIRED_FIELDS, RESOURCE_NOT_FOUND, UNAUTHORIZED, PERMISSION_DENIED, UNIQUE_VIOLATION and INTERNAL.

Fincore does not return 412 or 422 on any request. A rule failure that reads like a precondition is returned as 400 with FAILED_PRECONDITION. 422 appears only in the other direction, as a response your endpoint returns to a webhook.

Handling

HTTP	Typical action
`401`	Check `Authorization: Bearer <token>` or `x-api-key`, create a new token and retry once, and confirm the environment and client match.
`409`	Idempotency conflict: the same `Idempotency-Key` was reused with a different body, or the original request is still in progress.
`500`	Retry only if the operation is idempotent or after support confirmation.

Known messages

Operation	HTTP	`reason`	`error_detail` or cause
Any protected operation	`401`	`UNAUTHORIZED`	`Invalid Credentials`
Create Money Out transaction	`400`	`FAILED_PRECONDITION`	`The account does not have sufficient funds.` (`error_code` `10-E4120`)
Create Money Out transaction	`400`	`DATA_ERROR`	`Transaction description must have less than 40 characters length.`
Create Money Out transaction	`409`	`FAILED_PRECONDITION`	`Idempotency key does not match the request payload`
Create Money Out transaction	`409`	`FAILED_PRECONDITION`	`Operation money_out in progress`
Cancel a private account	`400`	`FAILED_PRECONDITION`	`Invalid account balance, account balance must be equal to 0`
Add an instrument to the trusted whitelist	`400`	`FAILED_PRECONDITION`	A whitelist rule was not met (`error_code` `20-E4120`).
Add an instrument to the trusted whitelist	`400`		`Instrument in whitelist already exists.`
Download a report file	`400`		`Invalid UUID format for client_id`, `Invalid report_type: <value>`, `clabe_number is required for account statement reports`, `Invalid clabe number`

Authentication errors

HTTP	Applies to	Cause	Action
`400`	Credentials, token creation	Missing or malformed request data, or the credential is inactive, deleted, or from another environment.	Validate UUIDs, required fields, and JSON syntax; confirm the credential is active and belongs to the same environment.
`401`	Credentials, token creation, protected endpoints	Missing, invalid, expired, or environment-mismatched API key or bearer token.	Check `Authorization` or `x-api-key`, regenerate the token, verify environment, or request credential rotation.
`404`	Credentials	Client or active credential was not found.	Confirm the `clientId` for the target environment.
`500`	Credentials, token creation	Unexpected server or downstream error.	Retry after confirming the operation is safe, then contact Monato with `client_id` and timestamp.

Operation	HTTP	When it happens
Retrieve client credentials	`400`	The `clientId` path parameter or request metadata is malformed.
	`401`	The `x-api-key` is missing, invalid, or not valid for the environment.
	`404`	No active credentials exist for the supplied `clientId`.
	`500`	Unexpected server error.
Create authentication token	`400`	Required credential fields are missing or malformed.
	`401`	The API key, client secret, or client relationship is invalid.
	`500`	Unexpected server error.

Status codes by operation

Operation	`400`	`401`	`403`	`404`	`409`	`500`
Retrieve client credentials	✓	✓		✓		✓
Create authentication token	✓	✓				✓
Retrieve SPEI participants		✓				✓
Retrieve client accounts	✓	✓				✓
Create a private account	✓	✓	✓			✓
Create a Business Unit private account	✓	✓	✓	✓		✓
Block, activate, cancel an account	✓	✓	✓	✓
List Business Units, create a Business Unit	✓	✓				✓
Retrieve a Business Unit	✓	✓		✓		✓
Mark a Business Unit as validated	✓	✓		✓
Register instrument, list instruments, retrieve instrument	✓	✓		✓		✓
Add an instrument to the trusted whitelist	✓	✓		✓		✓
Create Money Out transaction	✓	✓		✓	✓	✓
Start Penny Validation	✓	✓		✓	✓	✓
Retrieve a transaction	✓	✓		✓		✓
Refund a transaction	✓	✓		✓		✓
Register a webhook, list webhooks	✓	✓				✓
Retrieve, delete a webhook		✓		✓
Update a webhook	✓	✓		✓
Download a report file	✓	✓		✓		✓

The per-code causes for each operation are in the API reference and in each guide. For Money In and other webhook delivery response codes, see Webhook events.

Contacting support

When you escalate an issue to Monato, include:

Endpoint and HTTP method.
trackingId or transaction id, when available.
client_id.
HTTP status.
details[].metadata.error_detail.
Timestamp and environment.

Do not send full payloads, API keys, secrets, full CLABEs, card numbers or personal data.