diff --git a/src/docs/version_001/docsStructure.ts b/src/docs/version_001/docsStructure.ts index ef50294..f47a432 100644 --- a/src/docs/version_001/docsStructure.ts +++ b/src/docs/version_001/docsStructure.ts @@ -34,5 +34,11 @@ export const versionOne: DocsStructure = { copy: 'copy.md', example: 'example.md', }, + { + title: 'Error Handling', + folder: 'error_handling', + copy: 'copy.md', + example: 'example.md', + }, ], }; diff --git a/src/docs/version_001/error_handling/copy.md b/src/docs/version_001/error_handling/copy.md new file mode 100644 index 0000000..951c7e4 --- /dev/null +++ b/src/docs/version_001/error_handling/copy.md @@ -0,0 +1,27 @@ +# Error Handling {% #error-handling %} + +The Onspring API uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the `4xx` range indicate an error that failed given the information provided. Codes in the `5xx` range indicate an error within Onspring's servers. + +The internet is a big place and requests sent across the network should be treated as if they may fail at any time. We recommend that you implement a retry strategy for requests that fail. This will help to ensure that your application is able to recover from any network issues that may occur. + +Some 4xx errors will also include an `Error` object in the response body. This object can contain a message with additional information about the error. + +**Note:** The exception to the above is if you receive a `499` status code this indicates that the request has exceeded the 90 second timeout limit of our api gateway. This is not an error with the request itself, but rather a timeout. This is a result of the request taking too long to process. Typically this is due to a large amount of data being requested or a request triggering a lot of processing. If you receive this error, you should consider breaking up your request into smaller requests. + +## Error Properties + +{% table %} + +- Property Name +- Data Type +- Description + +--- + +- Message +- `string` +- A human-readable message describing the error. + +{% table %} + +**Note:** The `Message` property is not guaranteed to be present in the response body. The response body may be empty or contain other properties. diff --git a/src/docs/version_001/error_handling/example.md b/src/docs/version_001/error_handling/example.md new file mode 100644 index 0000000..80da449 --- /dev/null +++ b/src/docs/version_001/error_handling/example.md @@ -0,0 +1,26 @@ +# Error Code Summary + +{% code heading="ERROR CODES" defaultLanguage="text" %} + +```text +400 Bad Request - The request was unacceptable, often due to missing a required parameter. +401 Unauthorized - No valid API key provided. +403 Forbidden - The API key doesn't have permissions to perform the request. +404 Not Found - The requested resource doesn't exist. +499 Client Closed Request - Our API gateway closed the connection because the request exceeded the 90 second timeout limit. +5xx Server Errors - Something went wrong on Onspring's end. +``` + +{% /code %} + +# The Error Object + +{% code heading="ERROR OBJECT" defaultLanguage="json" %} + +```json +{ + "Message": "Client does not have access to read app: 1" +} +``` + +{% /code %}