Your Sitepass integration will have to deal with both responses and errors when making requests to the Sitepass API.Sitepass uses HTTP response status codes to indicate the success or failure of your API requests. If your request fails, Sitepass returns an error using the appropriate status code.In general, there are three status code ranges you can expect:2xx success status codes confirm that your request worked as expected4xx error status codes indicate an error because of the information provided (e.g., a required parameter was omitted, or an incorrect parameter was provided)5xx error status codes are rare and indicate an error with Sitepass serversSome 4xx errors that could be handled programmatically include an error code—a short string with a brief explanation—as a value for code. A server request failure, will include a message property that will further define the error and help your resolve the issue. Request IDEach API request has an associated request identifier. You can find this value in the response headers, under SP-Request-ID. You can also find request identifiers in the URLs of individual request logs in your log section of API keys. If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.Common Response Object PropertiesKeyTypeDescriptionsuccessbooleanIdentifies whether the request was successful dataobjectIf an endpoint returns data. Then the model of the response will be in this property metadataobjectIf the request is paginated, then the metadata object will contain all the parameters for this pagination PaginationAll top-level API resources have support for bulk fetches via "list" API methods. These list API methods share a common structure, taking at least these two parameters in the request object: limit, nextIndexlimit: The maximum number of items you want to be returned in the paginated list. This maximum number that can be sent is 100.nextIndex: The index at which you want the next set of items to start at.The response object will contain a metadata object with the following properties to aid with handling paginationKeycurrentPageintegerThe calculated current page for the request nextIndexintegerThe starting index for the next page.recordsPerPageintegerNumber of records per page.totalPagesintegerTotal number of pages available totalRecordsintegerThe total number of records that are in the request. Error HandlingYour Sitepass integration might have to deal with errors at some point when making requests to the Sitepass API. These errors fall into three major categories:Content error—Invalid content in the API request.Network error—Intermittent communication problems between client and server.Server error—A problem on Sitepass servers.Content errorsContent errors are the result of the contents of an API request being invalid and return an HTTP response with a 4xx error code. For example, the API servers might return a 401 if an invalid API key was provided, or a 422 if a required parameter was missing, or a 417 if the data entered is not as expected by the endpoint.Network errorsNetwork errors are the result of connectivity problems between client and server and return low-level errors like socket or timeout exceptions. For example, a client might time out while trying to read from Sitepass servers, or an API response might never be received because a connection terminates prematurely. A network error wouldn’t necessarily have otherwise been a successful request—it can also be another type of error that’s been cloaked by an intermittent problem.Rate LimitingThe Sitepass API employs a number of safeguards against bursts of incoming traffic to help maximize its stability. Users who send many requests in quick succession may see error responses that show up as status code 429. We have several limiters in the API, including:A rate limiter that limits the number of requests received by the API within any given second.For other APIs, Sitepass allows up to 10 read/write operations per second.Treat these limits as maximums and don’t generate unnecessary load. We may adjust limits to prevent abuse or enable well-behaved high-traffic applications. See Handling rate limits  for advice on handling 429s. If you suddenly see a rising number of rate limited requests, please feel free to reach out to support.Handling Rate LimitsA basic technique for integrations to gracefully handle limiting is to watch for 429 status codes and build in a retry mechanism. The retry mechanism should follow an exponential backoff schedule to reduce request volume when necessary. We’d also recommend building some randomness into the backoff schedule to avoid a thundering herd effect.Retrying RequestsThese types of error are where a request retries is the most obvious approach. When intermittent problems occur, clients are usually left in a state where they don’t know whether or not the server received the request. To get a definitive answer, they should retry such requests with the same request object and parameters until they’re able to receive a result from the server.Retry quickly after the first failure, and subsequent retries should be on an exponential backoff schedule, the assumption being that a single failure is often a random occurrence, but a pattern of repeated failures likely represents a chronic problem.Server errorsServer errors are the result of a problem with Sitepass’s servers and return an HTTP response with a 5xx error code. These errors are the most difficult to handle and we work to make them as rare as possible—but integrations should be able to handle them when they do arise.As with user errors, retrying requests usually produces the same result. The client can retry the request, but we advise against it because the original request may have produced side effects.You should treat the result of a 500 request as indeterminate. The most likely time to observe one is during a production incident, and generally during such an incident’s remediation. Sitepass examines these failed requests and try to appropriately reconcile the results of any mutations that result in 500. The exact nature of any retroactive changes in the system depends heavily on the type of request. For example, if creating an account results in 500 error but we detect that the account has been created, but has failed to update your connections usage we’ll try to roll it forward. If an error was recognized but not handled, we’ll try to roll it back. If this doesn’t resolve the issue, you may still see requests with a 500 error that produce user-visible side effects.