Oneflow Integration Platform

Use the Oneflow API to build powerful integrations to automate your contract management.

Handling errors with error codes

Error format

The error format follows the RFC 7807 - Problem Details for HTTP APIs standard except that we use the application/json content type, which has better support in client libraries.

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.

AttributeDescription
error_codeA code to categorize the error.
detailAn easy-to-read description of the error. It usually provides the reason for the error and a possible way to resolve it.
parameter_problemsOptional information in the form of the parameter names related to the error. The parameter names are mapped to the list of descriptions of what is wrong with the parameter.
request_idThe unique ID you should provide to our support team regarding an error.
statusThe HTTP status code of the error.
titleThe HTTP title of the error.
typeA link to more information about the error.

🚧

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.

Error CodeReasonResolution
4000000A generic error meaning something is wrong with your request.Please refer to the documentation and other attributes in the error response for more information.
4000001The "unknown" enum value is reserved for output and cannot be used in input requests.Check the documentation for possible enum values.
4000002You tried to add more members to the contract than the maximum allowed.Check the documentation on how to avoid adding too many participants to the contract.
4000003You tried to add a duplicate participant to the contract.Remove the participant with the identical attribute from the request.
4000004The file format is not allowed.Please check the documentation for valid file extensions.
4000005It is only possible to set a single PDF file as an extended PDF.Send a single PDF file and check the documentation on how to upload files.
4000007There is a conflict between the product's quantity amount and quantity type.Make sure the quantity amount complies with the quantity type.
4000008The supplied phone number is incorrect.Please check the allowed phone number format and change the incorrect phone number.
4000009The email address does not belong to a registered or active user in the Oneflow account.Please ensure the user with the email address has accepted the invitation to become a user and is an active user in the Oneflow account.

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.

Error CodeReasonResolution
4010000A generic error meaning something is wrong with your authentication credentials.Please refer to the documentation and other attributes in the error response for more information.
4010001The provided API token is invalid.Check the documentation on how to get a new API token.
4010002The email you provided is not registered or inactive in the Oneflow account.Please ensure that the user with the provided email address has accepted the invitation to be a user and is an active user in the Oneflow account.

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.

Error CodeReasonResolution
4020000This feature is not available on your current plan.You need to be on a paid plan to use this 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.

Error CodeReasonResolution
4030000A generic error meaning you are not allowed to execute this operation.Make sure that your application user can perform this operation.
4030001The specified extension is not enabled.Make sure that the extension specified in your request (directly or indirectly) is enabled.

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.

Error CodeReasonResolution
4040000The resource referenced in the request was not found in the expected location. It might have been deleted, or you might have no access to it.Please check that the object still exists in the specified location and that you still have permission to access it.
4040001The requested URL was not found on the server.Please check the URL for spelling mistakes, and check the documentation for available endpoints in the public API.
4040002The requested URL was not found on the server.Please use the API subdomain for requests to the public API.
4040003The template used to create the contract needs to be in the target workspace and must be active.Please share the template with the workspace where you want to create the contract and make sure it is active.
4040004One or more data fields were not found.Please check the custom_id of the data fields for spelling mistakes and check the documentation.

405

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

Error CodeReasonResolution
4050000The HTTP request method is not allowed for the requested URL.You need to use a method allowed for a specific endpoint. Please check the documentation for the methods allowed for the 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.

Error CodeReasonResolution
4090000A generic error meaning your request conflicts with the state of the Oneflow application.Look for additional hints in the error message and make sure the request complies with the information given in the endpoint documentation.
4090001The selected option is not available.Make sure that the necessary extension is enabled in the Oneflow application. Check that the option is listed as an available option before using it.
4090002The contract does not allow uploading attachments.Please check the documentation to learn how to upload files to a contract.
4090003The contract does not allow uploading an expanded PDF.Please check the documentation to learn how to upload files to a contract.
4090004There is a duplicate attribute in one or more data fields.Please make sure the attributes required to be unique contain no duplicates.
4090005There is a conflict between the delivery channel and the sign method.Please make sure that they are set to compatible values.
4090006Total files count exceeded for the contract.Please check the documentation for how many files a contract can have.
4090007The template does not have the main product group for setting products.Please check the documentation and ensure that the template has the main product group to set products via the API.
4090008The contract is not in the correct state.Please make sure the contract has been published.
4090009The product price_2 is disabled in the product table.Please make sure price_2 is enabled in the product table of the contract.
4090010The contract cannot be modified because it is signed.Please make sure that the contract is in the correct state for your request.

415

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

Error CodeReasonResolution
4150000A generic error code indicating that the request uses an unsupported content-type header.Please check the documentation to learn about the correct content-type header and correct any spelling mistakes.

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.

Error CodeReasonResolution
5000000A generic error code meaning that something went wrong in the Oneflow application.Please stand by while we resolve the issue or contact our support team for more information.

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.

Error CodeReasonResolution
5030000A generic error code meaning that our service is temporarily unavailable.Please retry your request later.

Updated 16 days ago


Handling errors with error codes


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.