Common Troubleshooting steps for Sophos Central API errors

In this section we'll cover some common errors that may occur with the APIs and some basic troubleshooting steps you can do to correct the errors

4XX Errors

401 "Unauthorized"

  • There is an error in the “client_id” or “client_secret” values within the authentication request
    • Validate client_id and client_secret values
      • Re-create the credentials in your respective Admin portal if they can’t be validated
  • The token time has expired as it is only valid for 1 hour (3600 seconds)
    • Request a new token and validate functionality in a subsequent request
  • The Authorization name/value pair is missing from the header
  • A required header parameter and value is missing
    • Validate the X-Partner-ID or X-Tenant-ID and values are correct and present in relevant headers

Example 401 error responses:
"errorCode": "oauth.invalid_client_secret",
"message": "Unauthorized",
"trackingId": "197a2922-65e4-4548-a0a1-79a13b12c8fc"

"error": "Unauthorized",
"correlationId": "cdf74ec9-4697-42ee-b57f-67e9d67bbe07",
"requestId": "0ca2e378-cf62-4267-abe7-c683e2d6006b"

403 “Forbidden”

  • The customer is requesting a tenant from a different partner account, The customer is a term customer and does not have Partner Assistance enabled, or the account is a trial account.
    • Validate the X-Parter-ID supplied in the header matches the authorized account
    • The X-Partner-ID is the ID returned from the “WHO AM I” API request
      • Execute the who am I request and use the returned ID in the header of subsequent requests
      • Confirm Partner assistance is enabled for the customer in Partner Dashboard
      • Confirm the account type in Partner Dashboard is not a trial accounnt

Example 403 error responses
"error": "Forbidden",
"correlationId": "2e9690fe-70d8-41c5-acd3-20be9dda0e3b",
"requestId": "ac1eb5a2-4d11-479b-a80d-1f2562b59adf",
"createdAt": "2020-01-14T16:29:46.556Z",
"message": "Access Denied"

400 “Bad Request”

  • There is a missing or erroneous comma, parenthesis, or quote in the RAW JSON
    • Mock request in Postman to determine which

Example 400 error responses
"error": "BadRequest",
"correlationId": "3f466bb4-0323-419f-9b6b-246395bae96e",
"requestId": "13ca2e37-3aeb-4873-81f8-3bf0dfc6b174"

404 “Not Found”

  • The unique ID of the object is not found in the system
    • Validate if the customer has already deleted or actioned the item or if there is a typo with the UUID

Example 404 error responses
"error": "resourceNotFound",
"correlationId": "49628b7a-f977-4fb5-8105-33905fda14c0",
"requestId": "2e5319c9-b106-4fc9-bc98-d0cad687260a"

429 ”Too many requests”

  • This is a result of exceeding our rate limiting or spike arrest policy.
    • Please follow the request intervals in our Rate Limiting guide
Time window Maximum Allowed
1 second 10 API calls
1 minute 100 API calls
1 hour 1000 API calls
1 day 50,000 API calls


5XX Errors

The below is a list of errors that typically mean a Sophos system error.

500 Internal Server Error

  • There was an unknown error processing the API call.

502 Bad Gateway

  • The website responding to the API request is unavailable.
    • This may be due to maintenance or temporary overload.

503 Service Unavailable

  • The service implementing the API is unavailable. It could be a temporary error that resolves itself.

Steps for resolution of 5XX errors

  • Check if there are there any current Sophos Central service warnings or outages
    • If the error is persistent and are repeatable, please raise a Technical Support case with Sophos Central Support, including the following information:
       Subject: New API 5xx error
       JSON or Raw/Curl output of your full query.
       JSON output of the full response returned.
       How often the failure is occurring