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 (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.
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 tokens. Additionally, security mechanisms may block requests that appear suspicious or malformed.Verify the scopes of your API token and request necessary permissions. Include a valid User-Agent header with every request. This is a standard HTTP best practice and helps our security systems identify legitimate clients and avoid blocking requests as suspicious or malformed.
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.
408Request Timed OutThe request took too long to complete (>60 seconds) and has been aborted - this could be due to integration provider rate limits or processing delays. StackOne automatically retries failed requests up to 5 times within the request lifetime before returning this timeout.Respect received Retry-After headers to alleviate pressure on provider systems and avoid concurrent requests to the unified API. The Retry-After header contains either the original provider’s retry guidance or a default 60 seconds.
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_errors for any additional information from the provider.
429Too Many RequestsRate limits exceeded. Can be returned by the underlying integration provider or StackOne. When received from integration providers, StackOne automatically retries up to 5 times using the provider’s Retry-After header before returning the original 429 response.Implement exponential backoff for retries and ensure your requests are within rate limits. StackOne handles automatic retries for provider rate limits, so you typically only need to handle the final 429 response. See Rate Limiting for more information.
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 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.
Note:For any unresolved issues or further assistance, feel free to contact our support team directly via your dedicated slack channel or at support@stackone.com.
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_errors array). For example, 404 error is returned, because an employee with id = 250 does not exist.
Provider Error Example