What is causing HTTP 503 responses on calls to Oracle B2C Service REST and/or SOAP APIs?
Environment:
Connect REST API, Connect Web Services for SOAP (CWS)
Oracle B2C Service
Oracle B2C Service Issue:
When using the Oracle B2C Service REST and SOAP APIs, clients may encounter HTTP 503 Service Unavailable responses. These responses typically occur due to API throttling, a built-in product feature that limits the rate of incoming API requests to maintain service stability.
Details about API throttling are available in the product documentation [here], the [REST API documentation], and the [SOAP API documentation] under the "API Throttling" section.
Resolution:
503 Service Unavailable due to Throttling
When API rate limits are exceeded, Oracle B2C Service will respond with an HTTP status code of 503
For SOAP APIs, please note the exception: throttling at the application layer returns a SOAP fault with HTTP 500 and OSVCStatus header set to 503, while gateway-level throttling returns a bare HTTP 503 without a SOAP fault.
Best Practices for Handling 503 Errors
Implement Retry Logic
HTTP 503 errors are often temporary, especially when caused by throttling. Clients should implement a retry mechanism to gracefully handle such responses. Suggested approach:
- Retry the failed request up to three times
- Introduce progressive delays between retries (e.g., 1s, 2s, 4s)
- Optionally add randomized jitter to avoid synchronized retries from multiple clients
This ensures that client applications remain resilient during short-lived service constraints without overloading the system.
Monitor and Log 503 Events
Record all 503 responses with key details such as:
- API endpoint
- Timestamp
- Request ID or correlation ID (if available)
- HTTP headers and error codes
This data helps with troubleshooting and can be shared with Oracle Support when needed.
Escalation
If 503 errors are frequent or do not resolve after retries:
- Review API usage for potential overuse or bursts
- Open a Service Request (SR) with Oracle Support
- Include request details, error headers, and timestamps
Note on Other 5xx Errors
While this article focuses on 503 responses, other 5xx errors such as 500, 502, and 504 may also occur occasionally. These errors are typically transient and can also be retried using the same retry strategy outlined above.
