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 CodeDescriptionProbable CauseRemediation Steps
400Bad RequestIncorrectly formatted request parameters (requests 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 that the request body is well-formed and all required parameters are included.
401UnauthorizedInvalid API key or access token. Double-check your credentials and ensure they're valid.
403ForbiddenStackOne API key provided or linked account token lacks required permissions or the linked account tokensVerify the scopes of your API token and request necessary permissions.
404Not FoundThe requested resource doesn't exist, possibly due to an invalid ID.Double-check the resource IDs in your request and ensure they are valid.
409ConflictThe resource to be created already existsCheck that the resource doesn't already exist before creating it
412Precondition FailedEndpoints 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.
422Unprocessable EntityThe payload data for creating a resource doesn't match what the endpoints expectVerify 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.
429Too Many RequestsRate limits exceeded. Usually returned by the underlying provider.Implement exponential backoff for retries and ensure your requests are within rate limits.
500Server ErrorInternal StackOne server issue.Notify StackOne support if the issue persists.
501Not ImplementedThis endpoint hasn't been implemented for this connected providerSkip the call or contact StackOne support for more information. View endpoint support via the the Meta endpoint.
502Bad GatewayThe underlying Provider API has returned a 500 errorRead any additional details available in the response data and ensure the resource exists



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.



When 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_errors array). For example, 404 error is returned, because an employee with id = 250 does not exist.

Provider error example