Benchling uses standard REST HTTP response codes to indicate success or failure of an API request. In general, 2xx indicates success, 4xx indicates an error on the user's end, and 5xx indicates an error on Benchling's end.

In general, error responses will be a JSON dictionary with the following fields:

typeThis is an error code:
- invalid_request_error means that one or more parameters of the request were invalid and should be adjusted
- authentication_error means that the user calling the API did not have access or was not correctly authenticated
- api_error means something went wrong on our end
messageThis is a human-readable message, which is useful for debugging and for showing a message in downstream applications.
errorIdThis is an ID of the error if it was recorded in our logging system. This ID should be presented to Benchling support to help troubleshoot issues.

Downtime

Benchling has system-wide scheduled downtime on the last Saturday of every month between 4:00pm - 6:00pm PT. Outside of this window, Benchling may schedule planned periods of downtime for system upgrades; these ad hoc periods will be scheduled and communicated on a tenant-by-tenant basis.

During these downtime windows the Benchling API will be unavailable, and will respond to any request(s) with a 503 Service Unavailable error. Apps and integrations should be built with these downtime periods in mind: Gracefully handle 503 Service Unavailable errors by returning user-friendly error messaging wherever possible, consider rescheduling requests and/or processes like data sync outside of downtime windows, and design integrations with recoverability in mind.