Derapi uses standard HTTP response codes to signal success or failure. In cases of failure, Derapi's response includes a description of the failure in JSON format.
Error response JSON format
Requests which cannot be satisfied by the Derapi API will usually result in a non-2xx HTTP response code (except in the case of list endpoints supporting partial failures, as detailed below). In such cases, the response body will be a JSON object following the Problem Details for HTTP APIs RFC, having at least the following fields:
{
"type": "https://docs.derapi.com/reference/errors#validation-error",
"title": "Invalid request",
}
The values of these fields will be identical for errors of a particular type. When additional information about the specific error instance being reported, the detail key will also be present:
{
"type": "https://docs.derapi.com/reference/errors#validation-error",
"title": "Invalid request",
"detail": "body: Additional properties are not allowed ('other' was unexpected)",
}
Partial-Success Responses
A number of Derapi endpoints report lists of resources, e.g., https://api.derapi.com/solar-inverters. These lists may aggregate responses from multiple backends. For these endpoints Derapi always reports success, even if one or more of the backend calls fail. For example, one of the backends may reject client's credentials, or be unavailable due to a network outage. In this case, Derapi reports responses from all other backends, and includes the name of the failing backend and a description of the problem in the errors object. An example response might look like this:
{
"solar-inverters": [
"https://api.derapi.com/solar-inverters/sma:12800016",
"https://api.derapi.com/solar-inverters/sma:12800017",
"https://api.derapi.com/solar-inverters/sma:12800024"
],
"errors":{
"solis": "Unauthorized: https://www.soliscloud.com:13333/v1/api/inverterList"
}
}
If all backend calls succeed, the error object is empty.
Specific error types
Validation error
This error is returned when the request submitted by the API caller did not conform to Derapi's API specification, or when it contained content which was otherwise semantically invalid. Validation failures may derive from problems within the request body, path, or query string parameters.
The detail key will contain a summary of any validation failures, and the errors key will contain a listing of each individual validation failure, with detail and pointer keys explaining the failure and providing a JSON Pointer to its source within the submitted document. For example:
{
"type": "https://docs.derapi.com/reference/errors#validation-error",
"title": "Invalid request",
"detail": "body: Additional properties are not allowed ('other' was unexpected) (and 1 others)",
"errors": [
{
"detail": "Additional properties are not allowed ('other' was unexpected)",
"pointer": "#"
},
{
"detail": "-1 is less than the minimum of 0",
"pointer": "#/duration"
}
]
}
VCM Not Configured
Returned for calls against VCM (Vendor Credential Management) endpoints when the associated account has not been configured for VCM.
The request should not be retried. Instead, contact [email protected] to configure VCM for your account to use this feature.
Unauthorized
Returned when a vendor backend rejects client credentials.
The request should not be retried. Instead, check your vendor credentials.
Not Found
Returned when a client requests a nonexistent resource from Derapi.
Exists
Returned when a client tries to insert a new record that conflicts with an existing one.
The conflict may be within Derapi's system, or proxied from a conflict received from a vendor backend.
Derapi Internal Error
Returned for unexpected errors that originate within the Derapi system itself.
These errors will not include the detail key, and will automatically notify Derapi engineers. Contact [email protected] for help diagnosing this type of error.
Backend Data Assertion Error
Returned when a vendor backend API returns data to Derapi in an unexpected or invalid format. This may be caused by an unannounced change to the vendor API, or a bug in the Derapi system itself.
Contact [email protected] for help diagnosing this type of error.
Backend Server Error
Returned when Derapi receives an error response from one or more vendor APIs.
Network Timeout
Returned when Derapi is unable to contact one or more backend vendor APIs due to a timeout.
Too Many Requests
Returned when too many requests have been made to a vendor backend within a given period of time.