Error Handling

HTTP Response Codes

In addition to detailed error messaging, RocketKOR uses standard HTTP response codes to indicate the status of a request. In general, codes can indicate a successful response (2xx range), a failed response due to the content or structure of the request, business validation errors, or request conflicts (4xx range), or a failed response due to an error on the RocketKOR server (5xx range). Most failed responses fall in the 4xx range due to missing/incorrect request parameters or invalid authentication information.

Common HTTP response codes include:

200 OK The request was successful and a response body was returned.

201 Created The request was successful and resulted in the creation of a resource.

204 No content The request was successful but did not return a response body.

400 Bad Request The request could not be processed due to an invalid structure or missing/incorrect information (for example, a required parameter is missing).

403 Unauthorized The caller doesn’t have the required permissions to perform the request.

404 Not Found The requested resource doesn’t exist.

409 Conflict The request conflicts with a previous request. For example, the provided idempotency key was already used for another request.

422 Unprocessable Entity The request failed due to business reasons, such as a business validation failure (account limit exceeded, etc).

429 Too many requests The client has exceeded the API call rate limit.

500 Internal Server Error The server encountered an unexpected condition that prevented it from fulfilling the request.

503 Service Unavailable A service is temporary off-line. The request can be retried after a short interval.

Error Messages

RocketKOR error messages use the following structure:

				
					{
  "timestamp": DateTime,
  "traceId": DateTime,
  "message": String,
  "errorCode": String,
  "errors": [
    {
      "path": "String",
      "message": "String",
      "errorCode": "String"
    }
  ]
}

timestamp Date and time the error occurred.

traceID ID used to trace the error. This value can be submitted to RocketKOR Support to help identify the problem.

message Description of the error.

errorCode RocketKOR error code. For details, see the next section, “Error Codes”.

errors (Optional) List of detailed errors. Includes the path of the request field that caused the error (path), error message (message), and error code (errorCode) for each error.

Error Codes

General

Error Code	Error Description
constraint-violation	The provided value violates constraint validation.
entity-already-exists	The entity already exists.
invalid	The provided value is not valid.
invalid-parameter	The provided value is invalid. This error is usually related to Java bean validation.
method-not-allowed	The provided HTTP method is not supported for this endpoint.
not-allowed	The provided value is not supported.
not-found	The entity was not found.
request-not-supported	The HTTP request method, content type, or other criteria is not supported.
unable-to-process	The request is well formatted but the request could not be processed.
unexpected-system-error	An unexpected system error has occurred. The request can be retried.

Transactions

In Service	Error Description
insufficient-limit	The transaction exceeds the configured transaction limits for the Business Account, Customer Account, or Financial Account.
invalid-for-solution	The transaction uses a solution that is not supported by the Provider. (For example, the transaction uses the ACH solution but the Provider does not support ACH transactions.)
non-sufficient-funds	The Financial Account does not have sufficient funds for the transaction.
outside-solution-window	The transaction cannot be created during the specified time period.
solution-config-not-found	The transaction uses an unknown solution. The transaction cannot be created.
status-not-allowed	The transaction status cannot be changed to the specified status.
transaction-pre-validation-error	Transaction pre-validation has failed. The transaction cannot be created.
transaction-validation-error	Transaction validation has failed. The transaction cannot be created.
txn-financial-account-inactive	The Financial Account ID is not active.
txn-financial-account-not-found	The Financial Account ID does not exist.
txn-no-provider	Your RocketKOR account is not linked to a Provider that can process the specified transaction type.
txn-provider-declined	The Provider declined the transaction.
txn-provider-error	The Provider did not process the transaction due to an error.
unsupported-transaction-type	The transaction reversal contains an invalid transaction type.

Multi-Leg Transactions

Error Code	Error Description
disbursing-timing-invalid	The scheduled start data and time for the disbursement leg (credit) transaction must be a future date and must occur after the funding leg (debit) scheduled start date.
funding-timing-invalid	The scheduled start date and time for the funding leg (debit) transaction must be a future date.
txn-financial-account-category-not-supported	The Financial Account category is not supported for multi-leg transactions.

Batch Transactions

Error Code	Error Description
ba_batch_limit_exceeded	The total transaction amount exceeds the parent Business Account transaction limit. The transaction batch cannot be processed.
batch-mode-not-supported	The transaction batch mode is not supported. The transaction batch cannot be processed.
cancel-batch-prohibit-status	The transaction batch cannot be cancelled while the batch status is PENDING.
exceeded-batch-size	The transaction batch size is larger than the allowed size. The transaction batch cannot be processed.
invalid-batch-size	The number of transactions does not match the batch transactionCount field. The transaction batch cannot be processed.
unmatched-batch-transaction-amount	The total transaction amount does not match the batch totalAmount field. The transaction batch cannot be processed.