Response Codes

This page details some of the response codes that may be returned by Onshape API endpoints. For each response code, we’ve provided a brief description of the response and recommended next steps.

Success (2xx)

The client call was successful.

200 OK

The client call was successful. No action needed.

204 No Content

The client call was successful, and there’s nothing to return in the response body. The empty response body cannot be parsed.

Redirect (3xx)

307 Temporary Redirect

The client call was successful, and a redirection URL was returned. Follow the URL provided in the response.

Client Error (4xx)

There’s an error with the client request. Find the error code below, and follow the instructions for resolution.

400 Bad Request

The request cannot be processed by the server due a client-side error. This could be a malformed request syntax or other issue. Check the request parameters (GET and POST) and request body (POST) to determine the cause of the failure.

401 Unauthorized

The request failed the authentication/authorization checks. This could mean you are not logged in to Onshape, your API keys are invalid or for a different server, OAuth failed, etc.

Make sure the client is authenticated.

403 Forbidden

The client doesn’t have the correct permissions to perform this operation. Check that the API Keys or OAuth authentication have sufficient permissions to perform the operation. For example, POST operations typically require write scope; if the API Key was created with only read scope, the server will return a 403 error.

You might also need to check document and user permissions. For more details, see Share Documents (for everyone) and Understanding and Administering Project Roles and Permission Schemes (for Enterprise users and administrators).

404 Not Found

The server can’t find what the client is looking for. For example, a 404 error will be returned if the client tries to make a GET request for a document that doesn’t exist.

405 Method Not Allowed

Use of that method is not supported. For example, you cannot perform a DELETE request on a document version, because versions are read-only. Only GET requests on document versions are allowed.

406 Not Acceptable

The server cannot provide a response for the media type requested. See https://datatracker.ietf.org/doc/html/rfc2616#section-6.1.1.

409 Conflict

The client call includes duplicate values, causing a conflict. Modify the request to remove any conflicting values.

415 Media Type Not Supported

The client call includes unsupported data types or invalid JSON. Review the client code. When performing data imports and exports, follow all Translation guidelines to ensure all media and file types are supported.

429 Too Many Requests

The client sent too many requests to this endpoint in the Onshape-defined time window. The number of requests allowed per time window vary and are subject to change; Onshape does not publish this information.

Every Onshape API response includes the X-Rate-Limit-Remaining header. This is the number of times you are allowed to call this particular endpoint again within the Onshape-defined time window. For example, the following response indicates that you can call this endpoint 3000 more times within the time window:

200 Response (Additional headers may be returned.)

<Response [200]>
{
    'Date': 'Tue, 22 Apr 2025 18:10:46 GMT', 
    'Content-Type': 'application/json;charset=utf-8', 
    'X-Api-Version': 'v10', 
    'On-Version': '1.196.54436.927372740f35', 
    'X-Rate-Limit-Remaining': '3000'
}

If you exceed this number of calls during the time window, you’ll receive the 429 response code with a Retry-After header. This is the number of seconds before the counter for this endpoint resets. You can use this value as a delay to prevent hitting the 429 error again.

In the example below, the user has 0 retries left in the X-Rate-Limit-Remaining header, and must wait 450 seconds before calling the endpoint again, as noted in the Retry-After header.

429 Response (Additional headers may be returned.)

<Response [429]>
{
    'Date': 'Tue, 22 Apr 2025 18:16:16 GMT', 
    'Content-Type': 'application/json', 
    'X-Api-Version': 'v10', 
    'On-Version': '1.196.54436.927372740f35', 
    'X-Rate-Limit-Remaining': '0', 
    'Retry-After': '450'
}

499 Timeout

This call is taking too long. Please try again later.

Server Error (5xx)

There’s an error with the Onshape servers. Find the error code below, and follow the instructions for resolution.

500 Internal Server Error

The request resulted in an error. Set a limit for the number of retries, and if the request continues to fail, reach out to support.

503 Service Unavailable

Something is wrong with the Onshape servers. Retry after the delay specified in the response. Set a limit for the number of retries, and if the request continues to fail, reach out to support.