Error codes

Grand Central uses status codes, errors, and responses to communicate the results of API requests. This page explains the status codes, error response structure, naming conventions for error keys, and common error codes used in Grand Central Unified APIs.

Status codes

A server issues status codes in response to a client’s request. The following table describes the standard HTTP status codes returned by Grand Central APIs.

Status code	Description
`200`	OK.
`201`	Created.
`204`	Success.
`400`	Bad request.
`401`	Unauthorized.
`404`	Resource not found.
`500`	Internal Server Error.
`504`	Gateway timeout.

An error code is a numeric or alphanumeric code that indicates the nature of an error and, when possible, why it occurred.

Generic errors

Generic errors apply across all Grand Central connectors and API operations.

Authentication and credential errors

The following table describes errors related to authentication and credentials.

HTTP error	Error code	Error key	Description
`400`	`GC001`	`INVALID_CREDENTIALS`	Invalid username or password.
`401`	`GC002`	`UNAUTHORISED`	Invalid authentication credentials for target resource.
`409`	`GC003`	`CONFLICT`	Unable to process request. Conflict with existing resource/record, or previous request with `X-MC-Correlation-ID=<Correlation-ID>` in process.
`403`	`GC004`	`FORBIDDEN`	User doesn’t have the required permissions.
`401`	`GC005`	`UNAUTHORISED`	Missing or invalid Referrer HTTP header.
`410`	`GC006`	`GONE`	Resource is permanently unavailable.
`400`	`GC007`	`INVALID_CREDENTIALS`	Missing or invalid Authorization Parameters.
`400`	`GC008`	`INVALID_TOKEN`	Token can’t be validated.

API connector-specific errors

The following table describes errors specific to API connector operations.

HTTP error	Error code	Error key	Description
`400`	`GC021`	`INVALID_API_OPERATION`	Incorrect API URI.
`400`	`GC022`	`URI_NOT_FOUND`	Invalid invocation of API.
`422`	`GC023`	`METHOD_NOT_IMPLEMENTED`	HTTP method for this operation isn’t implemented.
`400`	`GC024`	`INVALID_JSON_SYNTAX`	Invalid JSON received.
`422`	`GC025`	`REQUEST_VALIDATION_FAILURES`	Validation failure in request.
`422`	`GC026`	`SCHEMA_VALIDATION_FAILURES`	Request isn’t aligned with schema.
`500`	`GC027`	`INTERNAL_SERVICE_ERROR`	Unexpected error in the service.
`500`	`GC028`	`CORE_SERVICE_ERROR`	Unexpected error from the core. Check core message details.
`500`	`GC029`	`UNKNOWN_CORE_SERVICE_ERROR`	Unexpected error from the core.
`400`	`GC030`	`INVALID_PRODUCT_DETAILS`	Specified product details are invalid.
`429`	`GC031`	`TOO_MANY_REQUESTS`	Too many requests sent.
`400`	`GC050`	`INVALID_PAGINATION_OFFSET_VALUE`	Invalid offset value received. Value should be within `<valid-offset>`.
`413`	`GC052`	`MAX_FILE_SIZE_EXCEEDED`	The file size exceeds the limit of `<file-size-limit>`.
`400`	`GC053`	`MAX_FILENAME_LENGTH_EXCEEDED`	The filename exceeds the maximum limit of `<file-name-length>`.
`404`	`GC054`	`NO_RECORD(S)_FOUND`	No records found.
`400`	`GC055`	`CORE_REQUEST_VALIDATION_FAILURE`	Failed core request validation.
`404`	`GC056`	`INVALID_CONFIG_MAP_KEY`	Configuration map key not available for `{value}`.
`501`	`GC057`	`FEATURE_NOT_SUPPORTED_BY_CORE`	Core doesn’t support this feature.
`400`	`GC058`	`INVALID_STATUS_TRANSITION`	Status transition is invalid.
`422`	`GC059`	`INVALID_BANK`	Bank is invalid.
`422`	`GC060`	`TRANSACTION_PROCESSING_INCOMPLETE`	Transaction hasn’t completed processing.

Connection errors

The following table describes errors related to network connectivity and service availability.

HTTP error	Error code	Error key	Description
`504`	`GC061`	`REQUEST_TIMEOUT`	Request timeout.
`502`	`GC062`	`BAD_GATEWAY`	The server gateway received an invalid response for the request.
`504`	`GC063`	`GATEWAY_TIMEOUT`	Gateway communication timeout.
`503`	`GC064`	`SERVICE_UNAVAILABLE`	Required service is unavailable.
`503`	`GC065`	`CONNECTIVITY_ERROR`	Unable to connect with one or more systems.
`409`	`GC066`	`MAX_UNIQUE_ID_LIMIT_EXCEEDED`	Unique ID limit exceeded.
`400`	`GC067`	`INVALID_ENCODING`	Invalid encoding in the request.

Party errors

A party is a person or organization. In a banking context, a party is typically a customer with a product or arrangement in the core banking system. The following table describes party-related errors.

HTTP error	Error code	Error key	Description
`404`	`GC101`	`PARTY_NOT_FOUND`	Party with specified ID doesn’t exist.
`409`	`GC102`	`PARTY_ALREADY_EXISTS`	Party with specified ID already exists.
`404`	`GC103`	`NO_ACCOUNT(S)_FOUND_FOR_PARTY`	No accounts found for the specified party.
`404`	`GC104`	`NO_BALANCE(S)_FOUND_FOR_PARTY`	No balances found for the specified party.
`404`	`GC105`	`PARTY_NOT_FOUND`	Party or parties with the specified name doesn’t exist.

Account errors

The following table describes errors related to account operations.

HTTP error	Error code	Error key	Description
`404`	`GC201`	`ACCOUNT_NOT_FOUND`	Account doesn’t exist for the specified ID.
`409`	`GC202`	`ACCOUNT_ALREADY_EXISTS`	Account with specified ID already exists.
`404`	`GC203`	`NO_TRANSACTION(S)_FOUND_FOR_ACCOUNT`	No transactions found for the specified account.
`409`	`GC204`	`ACCOUNT_BALANCE_NOT_ZERO`	Can’t proceed with account closure if account balance isn’t zero.
`422`	`GC205`	`INVALID_STATUS_TRANSITION`	Invalid status transition.
`404`	`GC302`	`ACCOUNT_NOT_FOUND`	Account doesn’t exist for the specified ID.

Transaction errors

The following table describes errors related to transaction operations.

HTTP error	Error code	Error key	Description
`404`	`GC203`	`NO_TRANSACTION(S)_FOUND_FOR_ACCOUNT`	No transactions found for the specified account.
`404`	`GC201`	`ACCOUNT_NOT_FOUND`	Account with specified ID doesn’t exist.
`404`	`GC301`	`NO_TRANSACTION(S)_FOUND_FOR_ACCOUNT`	No transactions found for the specified account.
`404`	`GC303`	`TRANSACTION_NOT_FOUND`	Transaction with specified ID doesn’t exist.

Payment errors

The following table describes errors related to payment operations.

HTTP error	Error code	Error key	Description
`400`	`GC401`	`INVALID_PAYEE_OR_PAYER_ACCOUNT`	Invalid payee or payer account specified in the request.

Loan errors

The following table describes errors related to loan operations.

HTTP error	Error code	Error key	Description
`404`	`GC501`	`INVALID_LOAN_ACCOUNT_ID`	Loan account doesn’t exist for the specified ID.
	`GC502`	`INVALID_GRACE_PERIOD`	Invalid grace period value.
	`GC503`	`RESCHEDULED_REPAYMENT_BEFORE_DISBURSEMENT_DATE`	Repayment period is prior to account opening date.
`400`	`GC504`	`INVALID_LOAN_PAYMENT_ID`	Invalid loan payment ID.

Card errors

The following table describes errors related to card operations.

HTTP error	Error code	Error key	Description
`404`	`GC601`	`INVALID_CARD_NUMBER`	Specified Card Number doesn’t exist.
`422`	`GC602`	`INVALID_FINANCIAL_INSTITUTION`	Invalid financial institution. The provided institution is not recognized.
`422`	`GC603`	`PARAMETERS_NOT_SET`	Parameters aren’t set as of the effective date.
`422`	`GC604`	`INVALID_OPERATOR`	Invalid operator. The provided operator isn’t recognized.
`400`	`GC605`	`MANDATORY_FIELD_MISSING`	At least one of DDA, SAV OR CRC is mandatory.
`404`	`GC606`	`ISSUER_BANK_ID_NOT_FOUND`	Issuer Bank ID doesn’t exist.
`422`	`GC607`	`INVALID_CARD_COMBINATION`	Invalid combination for card number.
`422`	`GC608`	`INVALID_PREFIX_OR_ISSUER`	Invalid prefix or issuer bank ID.
`422`	`GC609`	`CUSTOMER_NOT_FOUND`	Customer not found.
`422`	`GC610`	`GENERATION_ERROR`	Random card number generation error.
`404`	`GC611`	`ACCOUNT_NOT_FOUND`	Account number doesn’t exist.
`422`	`GC612`	`DATABASE_ERROR`	A database error has occurred. Unable to process the request at this time.
`422`	`GC613`	`MODULE_LOAD_FAILURE`	Module load failure encountered. Unable to process the request at this time.
`422`	`GC614`	`NO_PRIMARY_CUSTOMER`	Account has no primary customers.
`422`	`GC615`	`RELATIONSHIP_REQUIRED`	Relationship is required.
`409`	`GC616`	`DUPLICATE_RECORD`	Duplicate record found.
`422`	`GC617`	`REQUEST_BLOCKED`	Request blocked.
`403`	`GC618`	`SIGNATURE_EXPIRED`	Signature has expired.
`400`	`GC619`	`CARD_NOT_ELIGIBLE`	Card not eligible.

Error responses

When an API request fails due to request errors or server errors, an error response message is returned in JSON format.

Format

Error responses use the following format:

[
  {
    "errorCode": "<error code goes here>",
    "errorMessages": [
      {
        "gc": "<grand central error message goes here>",
        "core": "<core error message goes here>"
      },
      {
        "gc": "<grand central error message goes here>",
        "core": "<core error message goes here>"
      }
    ]
  }
]

Examples

The following example shows an error response that includes core messages:

[
  {
    "errorCode": "GC001",
    "errorMessages": [
      {
        "gc": "gc error message1",
        "core": "core error message1"
      }
    ]
  },
  {
    "errorCode": "GC002",
    "errorMessages": [
      {
        "gc": "gc error message2",
        "core": "core error message2"
      }
    ]
  }
]

The following example shows an error response that doesn’t include core messages:

[
  {
    "errorCode": "GC005",
    "errorMessages": [
      {
        "gc": "shortName may only be 255 characters long"
      },
      {
        "gc": "dateOfBirth 1973-0131234-21324 is an invalid date"
      },
      {
        "gc": "lastName may only be 255 characters long"
      }
    ]
  }
]

Error mapping

The following tables show how core banking system error codes map to Grand Central error codes.

FIS IBS to Grand Central

The following table shows how FIS IBS error codes map to Grand Central error codes.

FIS code	GC code	Implemented connector
`4`	`GC055`	Common
`100`	`GC501`	Common
`116`	`GC205`	Common
`301`	`GC101`	Common
`428`	`GC201`	Common
`513`	`GC204`	Common
`900901`	`GC002`	Common
`900902`	`GC002`	Common
`CB00001`	`GC601`	Common
`CB00002`	`GC612`	Common
`CB00003`	`GC602`	Common
`CB00020`	`GC603`	Common
`CB00022`	`GC604`	Common
`CB00027`	`GC055`	Common
`CB00030`	`GC605`	Common
`CB00031`	`GC055`	Common
`CB00036`	`GC055`	Common
`CB00039`	`GC055`	Common
`CB00040`	`GC055`	Common
`CB00041`	`GC055`	Common
`CB00042`	`GC055`	Common
`CB00043`	`GC055`	Common
`CB00045`	`GC055`	Common
`CB00046`	`GC055`	Common
`CB00059`	`GC055`	Common
`CB00068`	`GC606`	Common
`CB00078`	`GC606`	Common
`CB00083`	`GC602`	Common
`CB00084`	`GC607`	Common
`CB00085`	`GC607`	Common
`CB00099`	`GC611`	Common
`CB00141`	`GC612`	Common
`CB00144`	`GC613`	Common
`CB00151`	`GC612`	Common
`CB00160`	`GC606`	Common
`CB00162`	`GC055`	Common
`CB00168`	`GC608`	Common
`CB00175`	`GC601`	Common
`CB00180`	`GC055`	Common
`CB00188`	`GC610`	Common
`CB00385`	`GC608`	Common
`CB01456`	`GC612`	Common
`CB01457`	`GC612`	Common
`CI00037`	`GC055`	Common
`CI00070`	`GC055`	Common
`CI00071`	`GC055`	Common
`CI00073`	`GC055`	Common
`CI00074`	`GC055`	Common
`CI00078`	`GC055`	Common
`CI00079`	`GC055`	Common
`CI00080`	`GC055`	Common
`CI00081`	`GC055`	Common
`CI00082`	`GC055`	Common
`CI00083`	`GC055`	Common
`CI00086`	`GC055`	Common
`CI00156`	`GC055`	Common
`CI00157`	`GC055`	Common
`CI00158`	`GC055`	Common
`CI00159`	`GC101`	Common
`CI00181`	`GC054`	Common
`CI00214`	`GC601`	Common
`CI00216`	`GC614`	Common
`CI00220`	`GC615`	Common
`CI00224`	`GC616`	Common
`CI00229`	`GC101`	Common
`CI00232`	`GC201`	Common
`CI00238`	`GC609`	Common
`CI00292`	`GC055`	Common
`CI00294`	`GC055`	Common
`CI00625`	`GC055`	Common
`CI00626`	`GC055`	Common
`CI00627`	`GC055`	Common
`DP08005`	`GC006`	Common
`LN00008`	`GC501`	Common
`LN08154`	`GC501`	Common
`MB09004`	`GC055`	Common
`MB09005`	`GC006`	Common
`MB09013`	`GC055`	Common
`MB90004`	`GC055`	Common
`DP08005`	`GC201`	`gc-fis-party-connector`
`MB09005`	`GC201`	`gc-fis-loan-transaction-connector`
`DP08005`	`GC201`	`gc-fis-deposit-transaction-connector`

Jack Henry Symitar to Grand Central

The following table shows how Jack Henry Symitar error codes map to Grand Central error codes.

Jack Henry Symitar code	GC code	Implemented connector
`100.10202`	`GC201`	Common
`10202`	`GC201`	Common
`100.10201`	`GC201`	Common
`10201`	`GC201`	Common
`1.10`	`GC201`	Common
`100.12003`	`GC204`	Common
`12003`	`GC204`	Common
`100.13039`	`GC302`	Common
`13039`	`GC302`	Common
`100.13030`	`GC302`	Common
`13030`	`GC302`	Common
`100.100005`	`GC202`	Common
`100005`	`GC202`	Common
`100.12003`	`GC055`	`gc-symitar-party-connector`
`100.100000`	`GC055`	`gc-symitar-party-connector`
`100.10202`	`GC101`	`gc-symitar-party-connector`
`100.1020`	`GC101`	`gc-symitar-party-connector`
`100.10202`	`GC501`	`gc-symitar-loan-transaction-connector`
`10202`	`GC501`	`gc-symitar-loan-transaction-connector`
`100.10201`	`GC501`	`gc-symitar-loan-transaction-connector`
`10201`	`GC501`	`gc-symitar-loan-transaction-connector`
`1.10`	`GC501`	`gc-symitar-loan-transaction-connector`
`12003`	`GC055`	`gc-symitar-loan-connector`
`100.10201`	`GC055`	`gc-symitar-loan-connector`
`10201`	`GC501`	`gc-symitar-loan-connector`
`100.10202`	`GC501`	`gc-symitar-loan-connector`
`10202`	`GC501`	`gc-symitar-loan-connector`
`party_100.10202`	`GC101`	`gc-symitar-loan-connector`
`party_10202`	`GC101`	`gc-symitar-loan-connector`
`100.12003`	`GC055`	`gc-symitar-deposit-connector`
`12003`	`GC055`	`gc-symitar-deposit-connector`
`party_100.10202`	`GC101`	`gc-symitar-deposit-connector`
`party_10202`	`GC101`	`gc-symitar-deposit-connector`

Mambu to Grand Central

The following table shows how Mambu error codes map to Grand Central error codes.

Mambu code	GC code	Implemented connector
`301`	`GC101`	Common
`4`	`GC055`	Common
`428`	`GC201`	Common
`2102`	`GC055`	Common
`100`	`GC501`	Common
`116`	`GC205`	Common
`513`	`GC204`	Common
`212`	`GC303`	Common
`212`	`GC301`	`gc-mambu-transaction-connector`
`4`	`GC055`	`gc-mambu-payment-connector` (if payee account is invalid, Mambu sends a generic request validation failure error)
`428`	`GC401`	`gc-mambu-payment-connector` (if payer account is invalid)

Overview

Grand Central connectors

Release notes

Error codes

Status codes

Error codes

Generic errors

Authentication and credential errors

API connector-specific errors

Connection errors

Party errors

Account errors

Transaction errors

Payment errors

Loan errors

Card errors

Error responses

Format

Examples

Error mapping

FIS IBS to Grand Central

Jack Henry Symitar to Grand Central

Mambu to Grand Central

Overview

Grand Central connectors

Release notes

​Status codes

​Error codes

​Generic errors

​Authentication and credential errors

​API connector-specific errors

​Connection errors

​Party errors

​Account errors

​Transaction errors

​Payment errors

​Loan errors

​Card errors

​Error responses

​Format

​Examples

​Error mapping

​FIS IBS to Grand Central

​Jack Henry Symitar to Grand Central

​Mambu to Grand Central

Status codes

Error codes

Generic errors

Authentication and credential errors

API connector-specific errors

Connection errors

Party errors

Account errors

Transaction errors

Payment errors

Loan errors

Card errors

Error responses

Format

Examples

Error mapping

FIS IBS to Grand Central

Jack Henry Symitar to Grand Central

Mambu to Grand Central