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,
  "error": String,
  "message": 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.

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

message Description of the error.

Error Codes

The following error codes are used to identify the type of error.

unexpected-system-error An unexpected system error has occured. The request can be retried.

financial-account-not-found The Financial Account ID does not exist.

financial-account-inactive The Financial Account ID is not active.

non-sufficient-funds The Debit Financial Account does not have sufficient funds for the transaction.

txn-no-provider The Debit Financial Account for a transaction is not linked to a Provider.

not-allowed The provided value is not supported.

invalid The provided value is not valid.