Unified API Error Codes and Troubleshooting Guide
StackOne Unified API: Error Codes & Resolution Guide
Encountering errors while interacting with APIs is a common occurrence. Although the StackOne unified API will try to remediate issues automatically, it is important to understand what each error code signifies.
This guide lists the error codes you may encounter while using the StackOne Unified API, the possible reasons behind these errors, and possible steps for resolution.
Understanding Error Codes
Below is a table detailing common error codes returned by the Unified API, their meanings, and common remediation steps:
| Error Code | Description | Probable Cause | Remediation Steps |
|---|---|---|---|
400 | Bad Request | Incorrectly formatted request parameters (request parameters do not follow expected schema and fail validation) | Ensure all request parameters are correctly formatted and try again. - Verify that the endpoint URL is correct. - Ensure the request body is well-formed and all required parameters are included. |
401 | Unauthorized | Invalid API key or access token. | Double-check your credentials and ensure they're valid. |
403 | Forbidden | StackOne API key provided or linked account token lacks required permissions or the linked account tokens | Verify the scopes of your API token and request necessary permissions. |
404 | Not Found | The requested resource doesn't exist, possibly due to an invalid ID. | Double-check the resource IDs in your request and ensure they are valid. |
408 | Request Timed Out | The request took too long to complete (>60 seconds) and has been aborted - this could be due to provider rate limits. | Respect received Retry-After headers to alleviate pressure on provider systems and avoid concurrent requests to the unified API. |
409 | Conflict | The resource to be created already exists | Check that the resource doesn't already exist before creating it |
412 | Precondition Failed | Endpoints using x-account-id may return 412 if the linked account is disabled. | Check the status of the linked account and enable it if necessary. |
422 | Unprocessable Entity | The payload data for creating a resource doesn't match what the endpoints expect | Verify that the data sent follows the StackOne API reference. Look at the additional details if available in provider_errorsfor any additional information from the provider. |
429 | Too Many Requests | Rate limits exceeded. Usually returned by the underlying provider. | Implement exponential backoff for retries and ensure your requests are within rate limits. |
500 | Server Error | Internal StackOne server issue. | Notify StackOne support if the issue persists. |
501 | Not Implemented | This endpoint hasn't been implemented for this connected provider | Skip the call or contact StackOne support for more information. View endpoint support via the the Meta endpoint. |
502 | Bad Gateway | The underlying Provider API has returned a 500 error | Read any additional details available in the response data and ensure the resource exists |
Note:
For any unresolved issues or further assistance, feel free to contact our support team directly via your dedicated slack channel or at [email protected].
The above guide aims to provide a comprehensive yet concise overview of the error codes you might face while interacting with StackOne Unified API, along with actionable troubleshooting steps to resolve them. The structured table facilitates quick reference, while the detailed explanations under each error code ensure a deeper understanding of the issues and their solutions.
provider_errorsWhen the underlying provider API returns an error, the StackOne unified API will include any data returned by the provider related to the error in the response data (in the
provider_errorsarray). For example, 404 error is returned, because an employee withid = 250does not exist.
Updated 12 days ago