> This page is for Developer Documentation.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.benchling.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.benchling.com/_mcp/server.

# Errors

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

| Field     | Description                                                                                                                                                                                                                                                                                                  |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`    | This 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 |
| `message` | This is a human-readable message, which is useful for debugging and for showing a message in downstream applications.                                                                                                                                                                                        |
| `errorId` | This 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.                                                                                                                                                           |

## Concurrent edits to notebook entries

Notebook entry content is protected by an editor lock so that concurrent edits from different clients don't overwrite each other. If you send an API request that mutates a notebook Entry (for example, updating fields on the entry or writing to a structured table inside it) while a user is actively editing that same entry in Benchling, the request is rejected with a `409 Conflict` response and no changes are applied.

For bulk requests, the conflict is reported per item using index-aligned validation errors, so you can identify exactly which entries in the batch were locked. The lock is held for the duration of the active edit session and released automatically when the user stops editing.

Apps and integrations that write to entries should handle `409 Conflict` responses by retrying after a short delay, or by scheduling the write for a time when the entry is not being actively edited.

## 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.