Error Codes & Handling

When interacting with the ClearSKY API, you may encounter various errors returned in the response. The following guidelines describe how to appropriately handle these errors.

Handling 5xx HTTP Status Codes

• HTTP 500:
  This status code indicates that something unexpected happened on the server.
  • Action:
    • Assume the error is due to a transient fault.
    • Implement retries with exponential backoff until you receive a 4xx or 2xx status code.

Handling 4xx HTTP Status Codes

A 4xx response indicates service errors that require specific handling based on the code received. Below is an example of a 4xx response:

{
    "Data": {
        "Property": [ "Property must <reason>" ]
    },
    "Succeeded": false,
    "Error": {
        "Message": "One or more validation errors occurred.",
        "Code": 992
    }
}

In the above example, the response did not succeed ("Succeeded": false) due to the error with code 992. Code 992 indicates that validation of the input for the request failed, with specific details provided in the Data section.

General HTTP 4xx Codes

• HTTP 401/403:
  Authentication/authorization failed – see the authentication documentation.

• HTTP 404:
  The requested resource was not found. Ensure the parameters are correct if a successful response was expected.

• HTTP 429:
  Too many requests were received. Adhere to the API Request Limits.

HTTP 400 Specific Error Codes

The following table outlines how to handle various 4xx error codes in detail:

Error Code	Description	Handling Instructions
992, 993	Request body or parameters were not formed correctly for the endpoint. The response may include details for each property that failed validation.	Adjust the request body or parameters as indicated by the error details.
994	Insufficient download credits to complete the request.	Understand the credit system and ensure sufficient credits are available.
1002	Satellite imagery was not available for the specified area and period.	Reconfirm that the area and period are correct, and that imagery should indeed be present.
1003	Maximum number of concurrent requests reached.	Reduce the number of concurrent requests to the maximum allowed (see ApiKey MaxConcurrentConnections).
1004	Maximum area in km² for the request reached.	Reduce the requested area to ensure it is within the allowed maximum (see ApiKey MaxCompositeAreaKm2).
1005	Maximum number of bands for the request reached.	Reduce the number of bands in your request to the maximum allowed (see ApiKey MaxTotalBands).
1006	The requested area and date are not covered by an order.	Create an order for the specified area and period.
1007	The requested area is inside a region that does not contain data (e.g., a water body).	Do not make further requests for this area.
1010	The requested area is not fully covered by data in the requested source UTM EPSG.	Either adjust your order to ensure full coverage or switch to UtmDataSelectionMode set to combined_utm for reprojection of data.
1014	Uncertainty data is unavailable for the specified area and date.	Remove the uncertainty band from the request or add an order that includes uncertainty.
1020	An order exists for the requested area and date, but the image has not yet been predicted.	Retry the request later, assuming the image will eventually be predicted.
1021	An order exists for the requested area and date, but no image is available due to storage expiration.	Do not retry, as the data is expired. Create a new order for historical data.