S3 API connection errors occur when an application or S3-compatible client cannot connect to object storage, or cannot perform a requested operation. The most common causes are wrong endpoint, bad credentials, region mismatches, network problems, or unsupported API requests.
To help you identify and resolve the problem, follow these steps.
The endpoint is the URL your application uses to connect to the object storage service. If the wrong endpoint is specified, the application will not be able to connect or the request will fail.
I will see to it that:
The endpoint is the storage service you are using.
The hostname is spelt correctly.
The endpoint uses the required protocol, typically HTTPS.
The application does not leverage an endpoint from another storage provider or region.
The Space name and object key are correctly specified.
If it was recently modified, update the endpoint in your application storage configuration and try the request again.
Authentication errors can occur if the access key or secret key is invalid, expired, revoked, or misconfigured.
To troubleshoot:
Ensure that the application is using the correct access key and secret key.
Look for accidental spaces or partial values.
Make sure the credentials are still active.
Ensure credentials have the necessary permission to perform the requested operation.
If the credentials were rotated, update the application configuration.
Keep secret keys private. Do not paste these into publicly available code, or share them in support requests.
Certain S3-compatible applications may require providing a region value when setting up the client or signing requests.
Requests may fail with signature or endpoint errors if the configured region is not the region expected for the storage service.
Make sure that the value in your Space region matches the one you set in your application or SDK. Different S3-compatible services do not use the same region names or defaults so do not assume that.
The API response often provides useful information about the cause of the failure.
Error or symptom | Possible cause | What to check |
|---|---|---|
| Insufficient permissions or restricted access | Credentials, access policies, and requested operation |
| Invalid or unrecognized access key | Access key value and status |
| Incorrect secret key, region, endpoint, or request signing | Credentials, region, system clock, and SDK configuration |
| Incorrect Space name or endpoint | Space name, endpoint, and region |
HTTP 404 | Incorrect object key or resource location | Object key, Space name, and request URL |
Connection timeout | Network issue or unreachable endpoint | Internet connection, firewall, DNS, and endpoint |
Unsupported operation or HTTP 4xx response | The API request or parameters may not be supported | API operation, request format, and service compatibility |
Exact error codes and responses can vary between storage services. Use the full error message to narrow down the cause.
If the application is not able to connect to the endpoint, verify that the endpoint is reachable from the machine running the application.
Check your Internet connection.
Ensure that DNS can resolve the endpoint hostname.
Verify if a firewall, proxy or network policy is blocking outbound HTTPS requests.
The system date and time may be incorrect. Please check that the date and time are correct. Wrong time settings can lead to request-signature failures.
If other applications can connect, but one application cannot, review the network and client configuration of that application.
The S3-compatible SDK or client must be configured with the correct endpoint, credentials and region.
Make sure that:
The application uses some SDK or client that interacts with your storage.
The endpoint is explicitly configured when needed.
The service has the correct region and request signing settings.
Request made with the correct Space name and object key.
The SDK version is compatible with the requirements of the application.
If your credentials and endpoint work in another compatible client, compare the configuration of the working client with those of the failin
Not all AWS S3 API operations or parameters are supported in the exact same way by S3-compatible services.
If the connection is successful, but a particular request fails, verify whether the storage service supports the request.
If an application tries to use a feature that isn’t supported, or that works differently in the storage service, the application can fail. Unsupported API operation will not be resolved by changing the endpoint or updating the credentials.
Review the service’s compatibility information and the SDK’s request documentation before changing the app.
Once the configuration has been corrected:
Save the changed endpoint, region, or credential settings.
If the application needs to refresh its configuration, restart the application.
Repeat the original request.
Verify the returned HTTP status and API error message.
If you have the right credentials, try a simple allowed operation like listing objects or getting a known file.
If the first call is successful and the second one fails, review the parameters, permissions, and API compatibility of the failing call.
Collect the following details for troubleshooting:
The exact API error message and HTTP status code.
The SDK or client name and version.
The configured endpoint and region.
The API operation that failed.
Whether the error occurs for all requests or only one operation.
Remove secret keys, authorization headers, passwords, and sensitive query parameters before sharing logs. These details can help identify whether the problem is related to connectivity, authentication, configuration, or API compatibility.