Error Handling

Beam uses HTTP response codes to indicate the success or failure of an API request.

In general:

• Codes in the 2xx range indicate success.
• Codes in the 4xx and 5xx range indicate an error.

When a request fails, Beam returns an error code and a short description as well as the HTTP status code. Use the error code to find out what went wrong, and to decide what your application should do next.

Example Common Error Responses:

• Invalid Authentication Credentials, the provided API key is invalid or does not match the merchant ID.

{
  "code": 401,
  "message": "invalid authentication credentials; invalid authentication credentials; authentication failed",
  "error": {
    "errorCode": "INVALID_CREDENTIALS_ERROR",
    "errorMessage": "invalid authentication credentials; invalid authentication credentials; authentication failed"
  }
}

• Not Found, the requested resource could not be found. This can happen if the resource ID is incorrect or does not exist.

{
  "code": 404,
  "message": "not found",
  "error": {
    "errorCode": "NOT_FOUND_ERROR",
    "errorMessage": "not found"
  }
}

Rate limits and retries

Beam limits how often you can call the API. If you go over the limit, Beam answers 429 with TOO_MANY_REQUESTS_ERROR instead of processing the request.

Retry with exponential backoff and jitter:

1. Wait a second or two after the first attempt.
2. Roughly double the wait after each attempt that fails.
3. Add a small random amount to each wait, so that your retries do not all happen at the same moment.
4. Give up after a few attempts, and report the problem instead of retrying forever.

This applies to polling too, not only to failed calls. Polling too fast is the most common way to reach the limit, so use the same backoff when you poll a charge, a refund, or a payment link for its status.

You can also retry 5xx responses and timeouts, because those requests may not have been processed. Send the same idempotency key each time, so a retry cannot charge or refund the shopper twice.