Error format

Monato products do not share one error format. Fincore, Billpay and Gift Cards, Direct Debit, Cash and Lottery each return a different body. Branch on the fields for the product you are calling.

Product	Error body	Error codes
Fincore	`code`, `message`, `details[]`	Error catalog
Billpay, Gift Cards	`error_type`, `error_message`	Billpay, Gift Cards
Direct Debit	`detail[]` on validation errors. Declined charges use `declined_reason` and `declined_reason_rail`.	Error codes
Cash	`response_code`, `response_text`, `result`	Cash API reference
Lottery	`errors[]` or `error`	Error codes

Fincore

Fincore returns gRPC-transcoded errors:

Fincore error

{
  "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"
      }
    }
  ]
}

details[].metadata.error_detail is usually the most useful value for troubleshooting. The HTTP status comes from details[].reason. Branch on reason, not on the number at the end 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.
`DATA_ERROR`	`400`	A field value is invalid for its type or format.
`MISSING_REQUIRED_FIELDS`	`400`	A required field is missing.
`VALUE_TOO_LONG`	`400`	A field is longer than its maximum length.
`UNIQUE_VIOLATION`	`409`	The resource already exists. In public flows this is the idempotency conflict.
`UNAUTHORIZED`	`401`	Credentials are missing, invalid, expired or from another environment.
`FORBIDDEN`	`403`	The client is not allowed to do this operation.
`RESOURCE_NOT_FOUND`	`404`	The resource does not exist for this client.
`INTERNAL`	`500`	Unexpected server or downstream error.

Fincore never returns 412 or 422. 422 only appears the other way round, as a response your endpoint returns to a webhook.

On 401, check your Authorization or x-api-key header, create a new token and confirm the environment. On 500, retry only if the operation is idempotent or after Monato support confirms it.

Billpay and Gift Cards

Billpay (v1) and Gift Cards return the same envelope:

Billpay and Gift Cards error

{
  "error_type": "PAYEE_ID_INVALID",
  "error_message": "Payee ID Invalid"
}

error_type: machine-readable error code. Branch on this.
error_message: human-readable description.

Gift Cards returns every error with HTTP 422 unless noted otherwise. In Billpay v1, payment and top-up errors also use 422. Some other Billpay v1 responses use a different body: 401 returns {"errors": ["Access denied"]}, and an unknown payee returns {"error": "..."}.

Direct Debit

Request validation errors return 422 with a detail list:

Direct Debit validation error

{
  "detail": [
    {
      "loc": ["body", "amount"],
      "msg": "Example validation message",
      "type": "example_error_type"
    }
  ]
}

Requests without a valid API key return 401 Unauthorized.

A declined charge is not an HTTP error. The charge includes declined_reason, a platform code such as insufficient_funds, and declined_reason_rail, the code returned by the banking network. See Error codes.

Cash

Cash operation errors return a response code and text:

Cash error

{
  "response_code": "60",
  "response_text": "Parámetros Incorrectos",
  "result": {
    "amount": 100,
    "external_user_id": "USER000000"
  }
}

HTTP	Meaning
`400`	Request parameters are invalid, malformed or missing.
`401`	`X-Client-Id` is invalid or the signature does not match.
`404`	The resource does not exist.
`422`	The request is valid but breaks a business rule.
`500`	Unexpected server error.
`503`	The service is under maintenance.

Webhook setup errors use a different body, with event: "webhook.failed" and an errors value.

Lottery

Authentication errors return a list of messages. Validation errors return one message.

{ "errors": ["Access denied"] }

{ "error": "Invalid input" }

When you contact support

Include the endpoint and method, the HTTP status, the error body, the transaction or tracking ID if you have one, your client ID, the timestamp and the environment. Do not send full payloads, API keys, secrets, full CLABEs, card numbers or personal data. See Support.