HTTPS and TLS 1.2 Required

Maximum Allowed Client Clock Skew

HTTP status code 401 (NotAuthenticated) is returned if the client's clock is skewed more than 5 minutes from the server's. To determine the server's clock time, use this curl command with the API endpoint:

curl -s --head <endpoint> | grep Date

For example:

curl -s --head https://iaas.us-phoenix-1.oraclecloud.com | grep Date

Request and Response Format

The Oracle Cloud Infrastructure APIs use standard HTTP requests and responses. Each may contain Oracle-specific headers for pagination, entity tags (ETags), and so on as described elsewhere in this topic and in the API documentation.

Each response includes a unique Oracle-assigned request ID (for example, bb3f3275-f356-462a-93c4-bf40fb82bb02) in the opc-request-id response header. If you need to contact Oracle about a particular request, please provide this request ID.

Many of the API operations require JSON in the request body or return JSON in the response body. The specific contents of the JSON are described in the API documentation for the individual operation. Notice that the JSON is not wrapped or labeled according to the operation's name or the object's name or type.

Make sure to set the Content-Type header to application/json in your POST and PUT requests that contain JSON in the body.

Error Format

If a request results in an error, the response contains a standard HTTP response code with 4xx for client errors and 5xx for server errors. The body also includes JSON with an error code and a description of the error. For example:

{
"code": "InvalidParameter",
"message": "Description may not be empty; description size must be between 1 and 400"
}

Request Throttling

Oracle Cloud Infrastructure applies throttling to many API requests to prevent accidental or abusive use of resources. If you make too many requests too quickly, you might see some succeed and others fail. Oracle recommends that you implement an exponential back-off, starting from a few seconds to a maximum of 60 seconds. When a request fails due to throttling, the system returns response code 429 and the following error code and description:

You can poll a resource to determine its state. For example, when you call GetInstance, the response body contains an instance resource that includes the lifecycleState attribute. You might want your code to wait until the instance's lifecycleState is RUNNING before proceeding.

Different resources take different amounts of time to transition between states. Therefore, the optimal frequency and duration parameters for a polling strategy can vary among resources. The Oracle Cloud Infrastructure SDK waiters use the following default strategy:

Use an exponential back-off, starting from a few seconds to a maximum of 30 seconds between poll attempts.

You can find your tenancy's OCID in the Console, in the footer at the bottom of the page. The tenancy OCID looks something like this (notice the word "tenancy" in it): ocid1.tenancy.oc1..aaaaaaaauwjnv47knr7uuuvqar5bshnspi6xoxsfebh3vy72fi4swgrkvuvq.

List Pagination

When you call a "List" operation (for example, ListInstances), you can paginate the results and limit the response to only one page of results. To do this, in the GET request, set the limit to the number of items you want returned in the response. The opc-next-page header will then appear in the response if there could be items left to get. Include the header's value as the page parameter in the subsequent GET request. Repeat this process until you page forward through the entire list.

Retry Token

For some operations you can provide a unique retry token (opc-retry-token) so the request can be retried in case of a timeout or server error without the risk of executing that same action again. The token expires after 24 hours, but can be invalidated before then due to conflicting operations (for example, if a resource has been deleted and purged from the system, then a retry of the original creation request may be rejected).

ETags for Optimistic Concurrency Control

The API supports etags for the purposes of optimistic concurrency control. The GET and POST calls return an etag response header with a value you should store. When you later want to update or delete the resource, set the if-match header to the ETag you received for the resource. The resource will then be updated or deleted only if the ETag you provide matches the current value of that resource's ETag.

Null vs. Empty Strings for Optional Parameters

If you send an empty string ("") as the value of an optional parameter, the API validates the value as normal (for example, checks against minimum and maximum allowed length, and so on). Often the minimum allowed length is 1, so an error would be returned. If you don't set the value (it's null), the API performs no validation, and some other action may occur. For example: if you don't set a value for the displayName when creating a new VCN object, the service will auto-generate a value.