API Error Codes

This article covers the HTTP status codes and error responses the ScopeStack API returns, organized by category. Each section explains what the error means and the steps to resolve it.

Required Request Headers

The headers required depend on whether you are reading or writing data.

GET requests (read operations):

POST and PATCH requests (create and update operations):

The Content-Type header is required only when sending a request body. Omitting it on a write request will result in a 400 or 415 error.

Authentication Errors

401 Unauthorized

Your access token is missing, invalid, or expired.

{
  "errors": [
    {
      "status": "401",
      "title": "Unauthorized"
    }
  ]
}

OAuth Token Errors (POST /oauth/token)

When requesting or refreshing a token, the response may include one of these error codes in the body:

Example error response:

{
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client."
}

Permission Errors

403 Forbidden

Your token is valid, but the user associated with it does not have permission to perform this action.

{
  "errors": [
    {
      "status": "403",
      "title": "Forbidden"
    }
  ]
}

Validation and Request Errors

400 Bad Request

The request was malformed or contained an unsupported parameter.

{
  "errors": [
    {
      "status": "400",
      "title": "Bad Request",
      "detail": "Filter not allowed: created-before"
    }
  ]
}

Common causes:

• A required field is missing from the request body
• A field value is the wrong data type (for example, a string where a number is expected)
• A filter parameter is not supported for this endpoint
• A page[size] above the maximum of 1000 (see Pagination)
• Invalid JSON:API formatting in the request body

Check the API documentation for the endpoint you are calling to confirm which fields are required, which filters are supported, and the expected data types.

422 Unprocessable Entity

The request was well-formed but failed validation. This is the most common error when creating or updating records.

{
  "errors": [
    {
      "status": "422",
      "title": "Unprocessable Entity",
      "detail": "Name can't be blank"
    }
  ]
}

The detail property in the error response identifies which field failed and why. Address each error in the errors array before retrying.

Not Found Errors

404 Not Found

The resource does not exist, it exists in a different account than the one your token is scoped to, or your API user is not allowed to see it.

{
  "errors": [
    {
      "status": "404",
      "title": "Not Found"
    }
  ]
}

Rate Limiting

429 Too Many Requests

You have sent too many requests in a short window. The response carries a Retry-After header and a JSON body naming the same interval:

{
  "error": "Rate limit exceeded. Retry in 60 seconds."
}

Retry-After is the length of the throttle window in seconds, not a countdown to the exact moment it resets. Waiting that long is always safe. The message wording differs slightly between hosts, so match on the 429 status rather than the text.

Read Retry-After and wait that long before retrying. Retrying immediately, or on a fixed short interval, keeps you inside the same window and prolongs the block. Use exponential backoff for anything automated.

The two hosts throttle different things, which is usually the key to an unexpected 429:

Common causes and how to fix them:

A sustained token loop returns 403, not 429. A client that keeps hammering POST /oauth/token past the sustained threshold is temporarily blocked by IP and gets 403 Forbidden with no Retry-After, until the ban expires (one hour by default). If you are seeing unexplained 403s from a machine that was recently minting tokens in a loop, that is the cause — not a permissions problem. Fix the token caching and wait out the ban.

Server Errors

504 Gateway Timeout

The server did not return a response in time. This typically occurs on requests that involve large amounts of data.

The most common cause is calling the merge data endpoint (GET /{account-slug}/v1/projects/{id}/merge-data) on a project with 20 or more service locations using the v1 response format. The server-side computation for large projects exceeds the request timeout.

How to resolve:

Switch to the v2 merge data format by passing version=2 as a query parameter:

GET /{account-slug}/v1/projects/{id}/merge-data?version=2

The v2 format is more efficient and handles large projects reliably. If you are using a reference project to generate merge data, consider using a smaller, representative project instead.

Quick Reference

Still seeing an error? Contact ScopeStack support via chat or email. Include the full error response, the endpoint you were calling, and whether you are using Postman, Workato, or custom code.