Dashboard refresh - 403 Forbidden - Documentation of errors

Question

I have a periodic scheduled job that refreshes a dashboard using this HTTP PUT request:

/services/data/v44.0/analytics/dashboards/somedashboardId

Mostly, this works reliably but every so often I get a 403 Forbidden.

OK, so a turn to the documentation in the Salesforce Reports and Dashboards REST API Developer Guide - Error Codes yields no mention of any 403 and, a sentence says

Dashboard-level error messages are returned in the response header

I dutifully dump out the response header and there's nothing of use there.

Transfer-Encoding=>chunked
X-Content-Type-Options=>nosniff
Date=>Tue, 15 Jan 2019 23:25:00 GMT
X-Robots-Tag=>none
Strict-Transport-Security=>max-age=31536000; includeSubDomains
Cache-Control=>no-cache,must-revalidate,max-age=0,no-store,private
Content-Security-Policy=>upgrade-insecure-requests
Set-Cookie=>BrowserId=DY_BeLonQN25FJCoj7J2kw;Path=/;Domain=.salesforce.com;Expires=Sat, 16-Mar-2019 23:25:00 GMT;Max-Age=5184000
Expires=>Thu, 01 Jan 1970 00:00:00 GMT
X-XSS-Protection=>1; mode=block
Content-Type=>application/json;charset=UTF-8
Sforce-Limit-Info=>api-usage=19067/625000

By chance, I was using Workbench and discover that the error details are in the PUT response body, not response header:

[ {
  "errorCode" : "FORBIDDEN",
  "message" : "You can't refresh this dashboard more than once in a minute."
} ]

and even worse, the documentation never even mentions this array of {"errorCode": "xxx", "message": "yyy"} objects

Before I file a doc bug, am I missing some doc reference to this response object?

Answer 1

At first, I felt like this should be a 400 error, then I realized that they are forbidding the action because it exceeds an API limit, which led me to Status Codes and Error Responses. The structure is (kind of) there:

{
  "message" : "The requested resource does not exist",
  "errorCode" : "NOT_FOUND"
}

And the 403 code is described as:

The request has been refused. Verify that the logged-in user has appropriate permissions. If the error code is REQUEST_LIMIT_EXCEEDED, you’ve exceeded API request limits in your org.

I'm not sure why your JSON results are returning as a list, but it feels like they were going for the standard feel of the main REST API.

I feel like this might be two errors. First, the documentation you linked should have mentioned this error, or made a link to the main REST API error code page. Second, the response does not match what the REST API documentation says it should, so there might be a need for them to patch that in a future version, or at least document that some requests may return different structures, etc.