2749091 - Protection Mechanism of Snapshot-based Pagination for OData API servers - COE_SNAPSHOT_BAD_REQUEST

• To protect API servers against  unintended bad requests, we introduced a protection mechanism to regulate the usage of snapshot-based pagination with the Q1 2019 Release
• This is applicable when snapshot pagination is enabled in OData API (paging=snapshot)

SuccessFactors API Server

Following are the sample error messages:

Entity level:

{

    "error": {

        "code": "COE_SNAPSHOT_BAD_REQUEST",

        "message": {

            "lang": "en-US",

            "value": "We have temporarily blocked the snapshot pagination request from companyUser <Company ID>|<API_USER> for entity <Entity_Name> until <Time Stamp for block time period> because too many consecutive requests have been attempted without accessing subsequent data. Please retry after you're unblocked and use $skiptoken to fetch the data of subsequent pages, otherwise you will continue getting the first page and be blocked again."

        }

    }

}

Company User level:

{

    "error": {

        "code": "COE_SNAPSHOT_BAD_REQUEST",

        "message": {

            "lang": "en-US",

            "value": "We have temporarily blocked the snapshot pagination request from companyUser <Company ID>|<API_USER> for all entities until <Time Stamp for block time period> because too many consecutive requests have been attempted without accessing subsequent data. Please retry after you're unblocked and use $skiptoken to fetch the data of subsequent pages, otherwise you will continue getting the first page and be blocked again."

        }

    }

}

This feature was introduced to ensure an efficient resource usage of API servers

To protect servers against intended or unintended bad requests, we have introduced a protection mechanism to regulate the usage of snapshot-based pagination.
A "quota" is imposed on the company user level and the entity level to restrict the number of bad requests that can be made within a given period of time.
Should the limit be reached, the request will be rejected by the server and an error message will be returned in response.
The user will be blocked for 30 minutes before another request can be made.

The following table summarizes how this quota works:

Feature Explanation:

 This is based on two levels

• Company User Level (Typically the API user making the calls)
• Entity Level (Which API is responsible for the bad request)

How the counts are calculated?

• Multiple bad requests on a single entity also count as one bad request on the company user level.

• Before the limit is reached, using $skiptoken in the "__next" parameter to request the subsequent pages will reset the count.

• If a user is blocked on the entity level, they can still access other entities.

• If a user is blocked on the company user level, they will not be able to access any entities in this company.

Note on MDF Entities

MDF Foundation Object support paging=snapshot.

A "X-SF-Paging" custom header is used for the entities which support fall-back logic. This means, once snapshot fails, the query will switch back to offset (this also means that, from an API user side, the user would need to know which paging mode was used)

MDF currently does not support such fall back logic (only support paging=snapshot).

Example:

A user has made three bad requests on three different entities a, b, and c, and another two bad requests on entity d, the counts of consecutive bad requests are:

If the user requests for the second page of entity d at this point, the counts will change to:

• Company user level: 0

• Entity level:

  • Entity a: 1

  • Entity b: 1

  • Entity c: 1

  • Entity d: 0

Snapshot-based Pagination Guide

company id blocked , COE_SNAPSHOT_BAD_REQUEST , paging=snapshot , responseCode=400 , KBA , paging=snapshot , q12019 , protection mechanism of snapshot , coe_snapshot_bad_request , LOD-SF-INT-ODATA , OData API Framework , LOD-SF-INT , Integrations , How To