• For loosely coupled clients where the exact shape of the data is not known before the call, if the server returns something the client was not expecting, the client must safely ignore it.

• Some services may add fields to responses without changing version numbers. Services that do so must make this clear in their documentation and clients must ignore unknown fields.

• Clients must not rely on the order in which data appears in JSON service responses.

• For example, clients should be resilient to the reordering of fields within a JSON object. When supported by the service, clients may request that data be returned in a specific order. For example, a service may support the use of the orderBy query string parameter to specify the order of elements within a JSON array.

Responses may sometimes be returned as a series partial sets. You may influence the behavior of State Street API services that offer following parameters to control the size of paginated responses:

• limit the number of records to return per page. If this value is zero, negative or unspecified, then a default page size will be used.
• offset indicates the number of records to skip.
• pageToken contains an opaque string supplied in the nextPageToken of the most recent response, which indicates the next page of data to return (a null nextPageToken value in a response indicates no additional results are available).

Please note that results, including record counts, may change across calls as underlying data changes.

Services are versioned using a Major.Minor scheme, and this version number will increment in response to any breaking API change. When the major version number increments, this signals that support for previous major versions will be deprecated in the future.

There are 4 different stages in an API’s lifecycle:

• Active: An active API version is the most current and fully supported API. Developers should use only active APIs when building new apps.
• Deprecated: A deprecated API version has been superseded by a newer API version. It is supported (such as bug fixes) for 6 months from the deprecation date. New apps will be denied access to deprecated APIs.
• Retired: A retired API version is no longer supported. APIs enter this state after at least 6 months in the deprecated state. Any application using a retired API must migrate to an active API.

These limits can be recognized by a 429 response code, which indicates that the caller has made too many calls. An example response is shown below.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 5
{
    "error":  {
        "code": "EAM-2003",
        "message": "The app has made too many requests in the time period.",
        "traceId": "0123456789abcdef"
    }
}

Should these error appear, it is important to wait for the amount of time specified in a response with a Retry-After header before retrying the request.