Error Codes and Troubleshooting - StackOne Hub Documentation

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 steps for resolution.

HTTP Error Codes

All StackOne API errors follow a consistent response format:

{
  "statusCode": 400,
  "message": "Human-readable error message",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "errorCode": "ValidationError",
  "provider_errors": []
}

Error Code Reference

Code	Name	Description
400	Bad Request	Invalid request parameters or malformed request body
401	Unauthorized	Missing or invalid API key, or expired credentials
403	Forbidden	Valid credentials but insufficient permissions
404	Not Found	Resource does not exist or was deleted
408	Request Timeout	Request took too long to complete
409	Conflict	Request conflicts with current resource state
412	Precondition Failed	Linked account belongs to a disabled integration
422	Unprocessable Entity	Request validation failed
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error: check status.stackone.com
501	Not Implemented	Feature not supported for this provider
502	Bad Gateway	Error from upstream provider

Common Error Scenarios

400 Bad Request

Causes:

Missing required fields in request body
Invalid field types (e.g., string instead of number)
Malformed JSON

Example response:

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    "first_name must be a string",
    "email must be a valid email address"
  ]
}

Fix: Check your request body against the API reference for required fields and types.

401 Unauthorized

Causes:

Missing Authorization header
Invalid API key
Expired OAuth credentials for linked account

Error codes:

Error Code	Meaning
`AccountInvalidCredentialsError`	Credentials rejected by provider
`AccountExpiredCredentialsError`	OAuth token expired
`AccountAuthenticationFailedError`	General auth failure

Fix:

Verify your API key is correct and has appropriate scopes
For expired credentials, ask your customer to re-authenticate via the Integration Hub

403 Forbidden

Causes:

API key lacks required scope
Linked account lacks permissions in the provider
Provider account settings restrict the operation

Fix:

Check API key scopes in the Dashboard
Verify the linked account has permissions in the provider’s admin settings

404 Not Found

Causes:

Resource ID doesn’t exist
Resource was deleted
Invalid account_id header

Fix: Verify the resource ID exists by listing resources first.

408 Request Timeout

The request took too long to complete. The response includes a Retry-After: 60 header. Fix: Wait 60 seconds and retry. For large data sets, use pagination with smaller page sizes.

412 Precondition Failed

Cause: The linked account belongs to an integration that has been disabled. Error code: AccountIntegrationInactiveError Fix: Re-enable the integration in Dashboard → Integrations, or ask the customer to re-link their account.

429 Too Many Requests

Rate limit exceeded. The response may include a Retry-After header. Fix:

Implement exponential backoff in your retry logic
Use the StackOne SDK’s built-in retryConfig option
Reduce request frequency

501 Not Implemented

The requested action isn’t supported for this provider. Fix: Check the Field Coverage page to see which operations are supported for each provider.

502 Bad Gateway

An error occurred when calling the upstream provider. Example response:

{
  "statusCode": 502,
  "message": "Bad Gateway",
  "provider_errors": [
    {
      "status": 503,
      "url": "/api/v1/employees",
      "raw": { "error": "Service temporarily unavailable" }
    }
  ]
}

Fix:

Check the provider_errors array for details about the upstream failure
The provider may be experiencing downtime. Check status.stackone.com for known incidents
Retry with exponential backoff

Provider Errors

When the underlying provider API returns an error, the StackOne Unified API includes any data returned by the provider in the provider_errors array:

{
  "statusCode": 404,
  "message": "Resource not found",
  "provider_errors": [
    {
      "status": 404,
      "url": "/api/v1/employees/250",
      "raw": { "error": "Employee with id 250 does not exist" }
    }
  ]
}

Always check the provider_errors array for additional context from the upstream provider. This can help diagnose issues specific to the connected system.

Getting Help

For any unresolved issues or further assistance, contact our support team via your dedicated Slack channel or at support@stackone.com.

Status Page

Check system status and incidents

Request Tester

Debug requests directly in the dashboard

Request Logs

View detailed request history

AI Error Explainer

Get AI-powered error resolution steps

​HTTP Error Codes

​Error Code Reference

​Common Error Scenarios

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​408 Request Timeout

​412 Precondition Failed

​429 Too Many Requests

​501 Not Implemented

​502 Bad Gateway

​Provider Errors

​Getting Help

Status Page

Request Tester

Request Logs

AI Error Explainer

HTTP Error Codes

Error Code Reference

Common Error Scenarios

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

408 Request Timeout

412 Precondition Failed

429 Too Many Requests

501 Not Implemented

502 Bad Gateway

Provider Errors

Getting Help