HTTP Error Handling

Guidelines for interpreting and handling HTTP 4xx and 5xx responses.

HTTP errors provide important information about how a request was processed and whether any action is needed from your system. This page outlines how to interpret the most common 4xx and 5xx responses returned by SiteMinder APIs, along with recommended handling strategies. Understanding these status codes will help you troubleshoot issues efficiently, ensure smoother message flows, and maintain a reliable integration.

Handling 400 Errors

4xx errors indicate that the request sent by your system cannot be processed due to an issue with the message itself—for example, missing fields, incorrect formatting, invalid credentials, or using an unsupported method. These errors require corrections on the client side before the request can be retried.

Error Code	Error Reason	Suggested Handling Method
400 – Bad Request	The request is malformed or does not meet the API specification (e.g., missing required fields, incorrect formatting, invalid characters, invalid XML/JSON).	Validate the structure and content of the request. Ensure that all required fields are present and formatted according to our API specifications. Correct the request and retry.
401 – Unauthorized	Authentication failed or required credentials are missing (e.g., incorrect username/password, missing or invalid token).	Confirm that the correct credentials and required authentication headers are being used. Update or refresh credentials if necessary.
403 – Forbidden	The request was understood, but the client is not authorised to access this resource.	Confirm that the credentials used have the required permissions. If access should be granted, contact the Partner Integrations team for assistance.
404 – Not Found	The requested endpoint does not exist, is misspelled, or is not enabled for the partner.	Verify the endpoint URL, including path and case sensitivity. Check the integration documentation to confirm that the endpoint is supported.
405 – Method Not Allowed	The HTTP method used is not supported for this endpoint.	Update the request to use the correct HTTP method as defined in the API specification.
406 – Not Acceptable	The server cannot return a response in the format specified by the request headers.	Confirm that the request’s Accept header matches the expected response type. Adjust the header or format before retrying.
409 – Conflict	The request conflicts with the current state of the resource (e.g., duplicate reservation, conflicting operation).	Review the logic triggering the request. Ensure that identifiers are unique and that duplicate messages are not being sent.
415 – Unsupported Media Type	The Content-Type header or payload format is not supported.	Update the Content-Type header and ensure the payload format matches the requirements for this endpoint.

Handling 500 Errors

5xx errors occur when the request is valid, but the server is unable to process it due to an internal problem or an issue with an upstream system. These errors are usually temporary, and in most cases, a retry strategy is recommended. If the error persists after retries, contact our Application Operations team for support.

Error Code	Error Reason	Suggested Handling Method
500 – Internal Server Error	The server encountered an unexpected condition and could not complete the request.	Implement a retry strategy to determine if the issue is temporary. If the error persists, validate the request. If the request appears correct, contact our Application Operations team.
501 – Not Implemented	The server recognises the request but does not support the functionality required to process it.	Do not retry. Confirm whether the requested operation is supported by the web service for this endpoint. Adjust the integration to use supported features only.
502 – Bad Gateway	The server, acting as a gateway or proxy, received an invalid or unexpected response from an upstream system.	Implement an Exponential Backoff strategy: 5 seconds → 10 seconds → 20 seconds → 40 seconds → then every 1 minute until a minimum timeout of 30 minutes. If the issue persists beyond the timeout, contact our Application Operations team.
503 – Service Unavailable	The server is temporarily unable to process the request due to high load or maintenance.	Use the same Exponential Backoff strategy recommended for HTTP 502 (minimum 30-minute timeout). If the service does not recover, contact our Application Operations team.
504 – Gateway Timeout	The server did not receive a timely response from an upstream system.	Apply the Exponential Backoff strategy (minimum 30-minute timeout). If the timeout continues beyond this window, contact our Application Operations team.
505 – HTTP Version Not Supported	The server does not support the HTTP protocol version used in the request.	Do not retry. Verify that the client implementation is using the correct HTTP version and configuration.