Misleading HTTP 200 Status on API Error Response (Code 603) with bulk API

[vholechi]

We’ve observed that the Bulk Export API returns an HTTP status of `200 OK` even when the response body contains an error. For example, we received the following response:
when using a bulk api i.e
bulk/v1/leads/export/{ExportID}/file.json

{
"requestId": "4aac#17c",
"success": false,
"errors": [
{
"code": "603",
"message": "Access denied"
}
]
}

Despite the `"success": false` flag and error code `603`, the HTTP status was still `200 OK`. This behavior is misleading and complicates error handling, as it suggests the request was successful when it clearly wasn’t.

We’d like to understand:
- Is this the expected behavior for the API?
- Are there plans to align HTTP status codes with the actual success/failure of the request?
- What is the recommended best practice for detecting and handling such errors?

Thanks

[SanfordWhiteman · Accepted solution]

Please use the Syntax Highlighter (“Insert/Edit Code Sample” on the button bar) to insert code so it’s readable. (I edited your post this time.)

Yes, this is expected and well-documented behavior. There’s no plan to change it.

Marketo’s “REST” API, like almost all such APIs, is more REST-like than fully REST-ful.* Application-level errors may be surfaced in the response body even with an HTTP 200.

If you’re building a Marketo integration, you need to process all API response bodies. If you weren’t doing that before, you cannot have coded for the API’s rate limits — those are only surfaced as inner error code 606, 615, etc. So your app will put other integrations at risk, along with itself.

Parse the JSON response for application level errors, i.e. "success": false and errors array, regardless of the HTTP status.

In the specific case of Bulk Extract, the Status endpoint gives you a fileChecksum to compare to the downloaded file. This would never match in the case where the Download File endpoint returns a response-level 603, so you can detect an error that way as well. But that obviously won’t work for any API scenario besides Bulk Extract!

* It doesn’t adhere to HATEOAS principles, for another example. Hardly anyone does!