Handling API errors
Every response with HTTP status code other than 200 should be considered erroneous, and contain information about an error that happened. Almost all errors follow the response format described in the following table:
| Name | Type | Verification | Description |
|---|---|---|---|
| Code | Int | Mandatory | Error code. |
| Message | String | Mandatory, Maximum length 1000 | Error text message. |
| ValidationErrors | InputValidationError[] | Optional Present if Code is 21xx | Array of validation errors. |
| MessageId | String | Mandatory | A unique identifier of the request. |
The following cases are exceptional and may not fit into the above format:
- 404 Not Found. Please refer to the relevant section.
Troubleshooting 400 Bad Request
If you receive a Bad Request response with 400 HTTP status code, it is most likely your request model is invalid or some business rules are violated.
Try to find the most appropriate solution in the following table:
| Code | Reason / solution |
|---|---|
| 2100 | Some fields of the request model are invalid. See ValidationErrors.Type and ValidationErrors.Message for details. Correct the request model, and try again. |
| 3000 | Generic business rule violation. Review the text in the Message. |
| 3001 | Work order state is invalid for this operation. For example, on an attempt to accept a work order in Paused status, this error occurs. Try retrieving the latest work order state and adjust your actions accordingly. If you think you did everything correctly, contact Corrigo support. |
| 3002 | This error occurs on attempt to accept a prebilled work order. The only way to accept a prebilled work order is to submit an invoice via CorrigoPro Desktop. |
| 3003 | This error code is usually returned if some of entities involved in a flow are not found. For example, a customer ID does not represent a valid customer. Check the property value, and try again. |
| 3004 | Quote submit is not allowed by your customer. Contact your customer via CorrigoPro Desktop. |
| 3005 | A work order is either not found, or it has been recalled by a customer. In any case, no actions can be performed. Try retrieving the latest work order state, and review the Status value. |
| 3006 | A work order is either not found, or it has been rejected. In any case, no actions can be performed. Try retrieving the latest work order state, and pay attention to Status value. |
| 3009 | Filling in the checklist is required to complete this work order. See Completing work orders and Completing checklist for more details. |
| 3010 | Some of the customer questions are required. For information on how to work with customer questions, see Completing work orders. |
| 3012 | Repair information is required to complete this work order. See Completing work orders for more details. |
| 3014 | Equipment worked on is required to complete this work order. See Completing work orders and Specifying equipment worked on for more details. |
| 3015 | This error occurs on specifying equipment worked on. A piece of equipment with Type = Excluding is already added to the current work order. No other items can be added. Remove this piece of equipment, and try again. See Specifying equipment worked on for more details. |
| 3016 | This error occurs on specifying equipment worked on. A piece of equipment with Type = Excluding cannot be added to the current work order, when any additional equipment records exist. Remove other pieces of equipment and try again. See Specifying equipment worked on for more details. |
| 3017 | This error occurs on assigning/divesting associates. A given associate does not exist in CorrigoPro Network. Try retrieving associate list, and check this associate exists. |
| 3018 | This error occurs on assigning/divesting associates. A given associate exists, but has no access to a provider branch, thus cannot be assigned to a work order. Try retrieving associate list, and check this associate exists. |
| 3019 | Quote submit failed. This error occurs if customer allows quote submit in general, but the particular operation failed. Most likely the quote is already Submitted or Approved. Review the text in the Message or try retrieving the latest work order state, and pay attention to NTE.Quote.QuoteStatus value. |
| 3020 | Some of the passed CheckListItem.Id values were not found in a work order. Try retrieving a check list for the work order, and make sure all ids are correct. |
| 3021 | No equipment assets can be linked to this work order. Possibly all available assets are already linked to the work order. |
| 3022 | Could not delete an equipment with the requested id because it does not exist. Try retrieving a list of equipment linked to the work order, and make sure you are passing the correct id. |
| 3023 | No available equipment asset with the requested id was found. Try retrieving a list of available assets, and make sure you are passing the correct id. |
| 3024 | There was an attempt to update one or more equipment attribute records, even though the current equipment doesn't have any linked attributes. For retrieving a list of equipment attributes, try using GET /api/equipment/details. |
| 3025 | No available equipment attribute with the requested id was found. Try retrieving a list of available attributes, and make sure you are passing the correct id. |
| 3026 | No available equipment with the requested id was found. Try retrieving a list of equipment linked to the work order, and make sure you are passing the correct id. |
| 3027 | Could not update a linked piece of equipment because relevant asset was not found for the requested asset id. Try retrieving a list of equipment linked to the work order, and make sure you are passing the correct ids. |
If you received an error with Bad Request HTTP status code, and API code is not listed above, try the following:
- Check Message property value. Usually it contains a human-readable description of the error. It may give you a clue on the exception source and troubleshooting steps.
- If error is still unclear, send the complete error object to Corrigo support.
Troubleshooting 401 Unauthorized
The request has not been applied because it lacks valid authentication credentials. This may happen in the following cases:
- Access token is not specified. Try requesting a token and sending it within request headers.
- Expired access token received. Try requesting a new token and sending it within request headers.
- Invalid access token received. Ensure you use correct client credentials of your company.
Troubleshooting 403 Forbidden
The request was understood, but an authorization error occurred while trying to process it. Review the Message text.
Suggested action:
If you believe this is not your fault, use exponential backoff, include a check before retrying non-idempotent requests. If this error happens again, send the error details to Corrigo support.
Troubleshooting 404 Not Found
CorrigoPro Direct API may return a Not Found response with 404 HTTP status code in the following cases:
Request size exceeds maximum allowed limit
In this case API error code is 2200. The maximum allowed request size is 20 MB. Most likely you are trying to upload a large file.
Suggested action:
Reduce the size of your request, and try again.
REST Service URL is obsolete or invalid
Suggested action:
Obtain a correct REST service URL by following the few simple steps:
- Log in to CorrigoPro Desktop
- Click on the CorrigoPro Direct widget
- Check the REST Service URL field
Troubleshooting 500 Internal Server Error
The server encountered an unexpected condition that prevented it from fulfilling the request.
Suggested action: Use exponential backoff, include a check before retrying non-idempotent requests. If this error happens again, send the error details to Corrigo support.
Updated almost 5 years ago