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 that the client is not logged in, API keys are invalid, 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 a particular endpoint in a given time window. The number of requests allowed per time window vary and are subject to change. Onshape does not publish this information. If the client receives HTTP 429 responses, delay and then retry, or reduce its request rate.

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.