Responses

When a response is returned, there are two key pieces of information to consider:

HTTP Status Code - This indicates the protocol-level status of the response.
Response Payload - This is the response body in a standard format that provides the application-level status, results, and any applicable errors.

Response Formats

All responses are returned in JSON format. JSON is a lightweight serialization language compatible with many programming languages. Since JSON is syntactically correct JavaScript code, you can use the JavaScript eval() function to parse it.

HTTP Status Codes

Our REST API uses standard HTTP status codes to indicate the success or failure of API calls. While Wikipedia provides comprehensive resources on HTTP status codes, here are the basics of what we return:

HTTP Code	Message	Description
200	OK	The request was processed and returned successfully. No changes were made.
201	Created	The new resource was created successfully.
400	Bad Request	Problem with the request, such as a missing, invalid, or type-mismatched parameter.
401	Unauthorized	The request did not include valid authorization credentials.
403	Forbidden	Access denied to private data, or you've exceeded the rate limit.
404	Not Found	The URL is incorrect, or the requested resource doesn't exist.
500	Server Error	We call this the "crap code" error. There's a problem handling the request on our end. If this persists, please contact support. We log and review all errors, but your feedback often helps us resolve issues more quickly.
503	Service Unavailable	Our API is temporarily down. Please try again. We work hard to keep this rare.

Non-2xx status codes correspond to various types of errors, which are detailed in the error responses section below.

Response Payload

Each API response is wrapped in a standard payload containing the API call results, plus additional useful information and metadata such as the total record count and result object type. Here's an example response:

{
  "status": "success",
  "count": 2,
  "type": "LoadServingEntity",
  "results": [
    {
      "lseId": 2756,
      "name": "Georgia Power Co",
      "code": "7140",
      "websiteHome": "http://www.georgiapower.com/"
    },
    {
      "lseId": 1,
      "name": "City of Augusta", 
      "code": "1000",
      "websiteHome": null
    }
  ]
}

The example above shows a successful call response. The result type is LoadServingEntity with two results. Note that results are always returned as an array, even when requesting a single object.

Name	Type	Description
status	String	Possible values: `success` or `error`
count	Integer	Total count of records matching your request. Due to pagination, this may not equal the number of records in the response
type	String	Resource (sometimes called Object) type
results	Object[]	Contains the actual results—the object or objects you requested

The count property indicates how many items matched your request's search criteria. We currently limit the count property to a maximum of 100,000. Interpret a count of 100,000 as "100,000 or more." Use the count property with Pagination Request parameters.

Response Payload Changes

We may occasionally add new fields to the set returned from a particular API endpoint. Generally, these new fields will only appear when you specify that the API should return the extended field set. However, API clients should always be prepared to handle (ignore) any new object properties they don't recognize.

Errors

Errors are communicated to the client in the response payload.

Errors in the Response Payload

The standard response payload can contain errors, providing detailed information about what specifically caused the problem. This allows you to respond appropriately, such as displaying validation messages to users or modifying the request at runtime.

{
  "status": "error",
  "count": 2,
  "type": "Error",
  "results": [
    {
      "code": "NotNull",
      "message": "An appKey must be supplied",
      "objectName": "requestSignature",
      "propertyName": "appKey"
    },
    {
      "code": "NotNull", 
      "message": "An appId must be supplied",
      "objectName": "requestSignature",
      "propertyName": "appId"
    }
  ]
}

Error Type Definition

The Error type has the following data definition:

Name	Type	Description
code	String	Error code. Unique string identifying the error type. See the table below for possible error codes. (Always returned)
message	String	Localized, user-readable message describing the error. (Conditionally returned)
objectName	String	Identifies the object type related to the error. Typically a resource type in the response, such as the `Tariff` object. (Conditionally returned)
propertyName	String	Identifies the object property related to the error. Primarily used for binding and validation errors, but sometimes for business logic errors too, such as `tariffId` or `lseId`. (Conditionally returned)

List of Error Codes

The code in the Error can be any of the following:

Name	Description
ObjectNotFound	Typically occurs when the item ID you provided was not found (e.g., passing a non-existent `masterTariffId`).
NotNull	A required object was not included in the request. Check `objectName` and `propertyName` for details.
InvalidArgument	An argument didn't meet validation requirements. This may or may not relate to the request parameters.
InvalidState	The current object state prevents the requested action from being performed.
TypeMismatch	An argument was not the expected type. This may or may not relate to the request parameters.
MissingId	An ID (usually `masterTariffId`) is required to process the request but wasn't provided.
DataIntegrityViolationException	The data sent was invalid. You may see this when trying to overwrite a value that cannot be overwritten.
InvalidFileFormat	The file format sent was invalid.
InvalidError	The supplied value is not valid.
ObjectCannotBeSaved	An error occurred while saving the object.
InsufficientPermissions	The supplied credentials don't have permission to access this resource.
SystemError	Unexpected exception occurred.
UniquenessViolationError	Only one object with this ID is allowed. Usually occurs when creating a new object with an existing `providerAccountId` or `providerProfileId`.
InvalidDateRange	The date range is invalid. Usually caused by `fromDateTime` being after `toDateTime`.