Codes, Statuses and Errors

Errors

For more information, please see the documentation at here.

There are two base error formats that can be returned in card issuing: Bad Request and Internal. Below are the common elements of both types of errors. Depending on the endpoint more fields may be available.

Bad Request Errors

Bad request error are any errors that can be resolved by the requester. This includes but is not limited to:

  • Malformed request body or URL
  • Resource not found
  • Request violates configuration or status of entity

In most cases a bad request can only be resolved by changing the request or making a change to the entity. There are some conditions that will resolve on their own, mostly status and limit conditions.

HTTP Status Codes

HTTP StatusDescriptionWhen Used
400Bad RequestThe request is invalid given the current configuration of your program.
401Unauthorised
404Not FoundThe requested resource was not found.
429Too Many RequestsToo many requests have been received in a short time-frame.

Body Response Format:

{
    "error": {
        "code": "Error code that can be programmatically checked against",
        "message": "Human readable error message, subject to change"
    }
}

Internal Errors

Internal errors are errors that are encountered in fulfilling a request that cannot be resolved by a caller. In general, errors with HTTPS status codes 503 and 504 will resolve themselves after a period of time.

Internal errors are returned with a tracking code. This code is used to help investigate or reconcile issues that have occurred.

HTTP Status Codes

HTTP StatusError CodesDescriptionWhen Used
500internal_error, internal_server_errorInternal ErrorInternal error within card-issuing platform.
502bad_gatewayBad GatewayInternal error, not recoverable. Please contact Berkeley if you encounter this error.
503transitory_failureService UnavailableThe request cannot be processed at this time. Under most circumstances this error will resolve quickly and the request can be retried.
504gateway_timeoutGateway TimeoutA request has timed out, however may have completed successfully. Under most circumstances this error will resolve quickly. For requests that use an idempotency key the request can be retried with the same key. We do recommend that clients check the status of a request using the appropriate get/list method.

Body Response Format:

{
    "error": {
        "code": "Error code that can be programmatically checked against",
        "message": "Human readable error message, subject to change",
        "tracking_code": "41519fff-439c-4d3d-ab33-4b74c763d2de"
    }
}

Cardholders, Accounts and Cards

The actions that can be performed with a card or account are limited by their status. For actions taken through the API or through Berkeley’s portals only the account status is relevant.

Of special note is the status awaiting_processor. While accounts do not need to be active to load accounts in this temporary state will fail to load. It is possible to retry the load after this state has cleared.

Statuses

StatusDescriptionNotes
awaiting_processorThe processor has agreed to create an account but the account is not yet ready. This state usually resolves in less than an hour.Temporary state. Card operations including loading cannot be performed.
shippingCard is waiting to be shipped.
shippedCard has been shipped.
not_activeThe account or card is inactive. It can be activated via an IVR or by the Activate Card endpoint.Value loads and transfers are possible. However, the cardholder will not be able to use the card for purchases.
activeThe account or card is active.
suspendedThe account or has been suspended.
expiredThe account or card is expired.
cancelledThe account or card is cancelled.
lostThe account or card has been reported lost.
stolenThe account or card has been reported stolen.
delinquent
closedThe account or card has been closed.

Value Loads

Limit Based Errors

Value loads are subject to limits on the amount of funds and the number of load operations that can be completed. These limits are set up on a per program basis.

Below is a table of error codes associated with load limits:

CodeDescription
load_limit_excededThe amount of funds requested is more than the maximum amount or less than the minimum amount for a value load.
velocity_check_failedA time based limit on value loads has been reached. This can either be the total amount or total number of loads in a given time period.
insufficient_fundsThere are not enough funds in the Master Funding Account to complete the load.
limit_excededThe value load would violate a limit that has not been classified as a load limit or a velocity limit.

Value Load Transaction Codes

Please contact support to see if the following codes are relevant/available on a per program basis.

The following transaction codes can be passed in the transaction_code field for both value load and unload.

transaction_code

transaction_code
cashback
atm_reimbursement_domestic
atm_reimbursement_intl

ACH

ACH is a batch process. This means that when an ACH transaction is created it is not yet completed. It’s status can be checked using the ACH Transaction History endpoint.

ACH Status Codes

These status codes shows the processors current progress in completing the ACH transfer.

CodeDescriptionNotes
queued_for_transferTransfer has been received and is waiting to be sent.
sentTransfer has been sent.
approved_after_limit_violationTransfer is approved.
cancelled_after_limit_violationTransfer has been cancelled.Terminal
cancelled_due_to_violation_of_debit_limitTransfer has been cancelled.Terminal
cancelled_at_cardholders_requestTransfer has been cancelled.Terminal
cancelledTransfer has been cancelled.Terminal
pending_for_approval_as_limit_exceededTransfer is waiting special approval.
deleted_by_cardholderTransfer has been deletedTerminal
bad_routing_numberThe routing number is incorrect.Terminal
on_holdThe transfer is on hold with the processor.
errorThe transfer has encountered an error and will not be completed.Terminal

📘

Related pages:

Card Issuing Certification and Onboarding
Secondary Authorizations
Simulate Authorization and Settlement