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
• 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, or it exists in a different account than the one your token is scoped to.

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

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.