Handling errors with error codes

Error format

Let's consider an error example and explain its important components. The following error might occur if you try to create a contract and use a template ID that has been accidentally deleted.

{
    "error_code": 4040000,
    "detail": "An object referenced in the request was not found. It might have been deleted or you might have lost access to it. Please check that the object still exists and you still have permission to access it.",
    "parameter_problems": {},
    "request_id": "Bp1JbY53dEBIS-DKf6VqOIgGsBw4yEOdR_aTUACrK5UROLoDf1JmcA==",
    "status": 404,
    "title": "Not Found",
    "type": "https://api.oneflow.com/v1/error_codes/4040000",
}

First, the error_code gives you more insight than the HTTP status code displayed as status. You might have noticed that the error_code starts with a status code, so you can roughly categorize the error from that alone. In this case, we got an HTTP 404 status code, which means that a specific resource was not found.

Error codes that end with 0000 are generic errors and should not be relied on directly. In such cases, you can still rely on the HTTP status code, like the HTTP 404 status code in this case. The reason is that we might, for instance, change the error code from 4040000 to 4040042 if we notice that it is worth providing you with more specific information about the error.

All error codes ending in a number larger than 0000 can be relied upon to identify and handle specific error scenarios. We have documented all of the error scenarios below.

🚧

Note:

The information in the error message is intended only for the integration developers and should be logged to give a sound basis to improve your integration. You can use the error code for the integration customers to identify a specific error scenario and show an appropriate message to the end-users.

🚧

Note:

The detail and problem_parameters attributes are only used to help new developers try out the API and should not be used for integration.

Error handling

🚧

Note:

Please, do not rely on the messages in the generic error codes ending in 0000, as we will improve them over time as we see fit.

For the best user experience, make sure to handle all of the error codes below in a user-friendly way. Try to resolve an error automatically or failing, otherwise, show a user-friendly message explaining why the error occurred and what the user can do to resolve it.

For the best developer experience, log the errors that occur to get instant feedback if you have a bug in your code and get more information when trying to identify a problem in your application after the event. Furthermore, you can forward the complete error response to our support team if you cannot resolve the issue on your own.

Error codes

400

These errors occur when there is a mistake in the request made to Oneflow. The error descriptions will help the developer to identify and fix the problem in the integration.

401

These errors occur when something is wrong with the provided authentication credentials. The user's email address might be incorrect, or an invalid API token was provided.

402

These errors occur when a feature is not available in the user plan. For example, users on a free plan are not allowed to use the publish contract feature.

403

These errors occur when the provided authentication credentials prevent you from making this request. For example, the user you specified might not have access to the affected resource, or the current configuration in Oneflow makes it impossible to complete the request. The first step, in this case, is to make sure the specified user can take action when they are logged in to the Oneflow app.

404

These errors occur when the request references a resource that does not exist, or the current user cannot see it due to access restrictions. For example, if you try to create a contract from a template that does not exist in the workspace where you create it, you will get an error since the application expects the template to exist in this workspace.

405

These errors occur when you try to make an API call using a method that is not allowed for a specific endpoint.

409

These errors occur when your request conflicts with the state of the Oneflow application. You can get this type of error when your request tries to create a contract with an attachment from a template that does not allow adding attachments.

415

These errors occur when your request uses an unsupported content type header when sending data to Oneflow.

500

These errors occur when something went wrong inside the Oneflow application. We automatically get informed about these errors and strive to quickly resolve them to provide you with the best service possible.

503

These errors occur when our service is temporarily unavailable. We automatically get informed about these errors and strive to quickly resolve them to provide you with the best service possible.