Beam logo

Error

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 indicates an error.

In addition to the HTTP Code returned when an error occurs, we also return an error code enum along with a short description to help you figure out what went wrong and to build your app accordingly.

Status Code Error Code Enum Description
2xx - Everything worked as expected. No errors here.
400 Bad Request INVALID_JSON_ERROR Bad or malformed JSON request
400 Bad Request API_VALIDATION_ERROR Inputs are failing validation. Check the message for details and retry.
401 Unauthorized INVALID_CREDENTIALS_ERROR Missing valid authentication credentials (e.g. no Authorization header).
403 Forbidden NO_PERMISSION_ERROR Request is authenticated but not authorized to perform the action.
404 Not Found NOT_FOUND_ERROR The requested resource doesn't exist.
412 IDEMPOTENCY_KEY_ERROR The same idempotency key was already provided with a different payload
422 MERCHANT_STATUS_INVALID_ERROR The merchant status is currently invalid so the requested action is blocked. Please contact our support team.
5xx - Something went wrong on our end. (These are rare.)

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"
  }
}