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