Responses

Handle Switch API responses by checking both the HTTP status code and the JSON response payload.

After you build a request with the conventions in Requests, use this page to parse successful payloads, inspect errors, and decide whether your client should retry, show a validation message, or change the request. If you are choosing where to start, see Getting Started.

Each response includes two layers of status information:

HTTP status code: Indicates the protocol-level outcome of the request.
Response payload: Contains the application-level status, results, metadata, and any errors.

Response formats

All Switch API responses are returned as JSON. JSON is a lightweight serialization format that is compatible with most programming languages and integration tools.

HTTP status codes

Switch REST APIs use standard HTTP status codes to indicate whether a request succeeded or failed:

HTTP Code	Message	Description
200	OK	The request was processed and returned successfully. Nothing was changed.
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 have valid authorization credentials.
403	Forbidden	Private data you are not allowed to access, or you have hit a rate limit.
404	Not Found	Your URL is incorrect, or the requested resource does not exist.
500	Server Error	We had a problem handling the request. If this error persists, contact support. We log and review all errors, but your reports often help us fix them more quickly.
503	Service Unavailable	Our API is down. Please try again. We work hard to make this rare.

Non-20x status codes indicate an error. Use the response payload to find the specific error code and message.

Response payload

Each API response is wrapped in a standard payload that contains the results of the API call and metadata, such as the total count of matching records and the result object type.

This example shows a successful 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
  }]
}

In this response, the result type is LoadServingEntity and there are two results. The results field is always an array, even when you request one object.

Name	Type	Description
status	String	Possible values are `success` and `error`.
count	Integer	Total count of records that match your request. Because of pagination, this is not necessarily the number of records in the response.
type	String	Resource (sometimes called the Object) type.
results	Object[]	Contains the object or objects that you requested.

The count property tells you how many items matched your request criteria. The count property is limited to a maximum of 100,000, so interpret a count of 100000 as "100,000 or more." Use count with pagination request parameters.

Response payload changes

From time to time, we may add fields to a particular API endpoint. In general, these new fields appear only when you request the extended field set. However, your API client should be prepared to ignore object properties it does not recognize.

Errors

Errors are returned in the response payload.

Errors in the response payload

The standard response payload can contain one or more errors. Use the error code, message, objectName, and propertyName fields to decide whether to show a validation message, retry the request, or change the request before sending it again.

{
  "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. This unique string identifies the type of error. Always returned.
message	String	Localized user-readable message describing the error. Conditionally returned.
objectName	String	Type of object related to the error. This is typically a resource type that is part of the response, such as `Tariff`. Conditionally returned.
propertyName	String	Property related to the error. Primarily used for binding and validation errors, but sometimes used for business logic errors, such as `tariffId` or `lseId`. Conditionally returned.

List of error codes

The code value in an Error object can be any of the following:

Name	Description
ObjectNotFound	Typically this is when the item id you passed in was not found. For example, passing in a non-existent `masterTariffId`.
NotNull	A required object was not passed in on the request. Check the `objectName` and `propertyName` for more information.
InvalidArgument	An argument passed in did not meet validation requirements. This may or may not be related to the request parameters passed in.
InvalidState	The current state of the object in question prevents the requested action from being performed.
TypeMismatch	An argument was not of the expected type. This may or may not be related to the request parameters passed in.
MissingId	An ID (usually a `masterTariffId`) is required to process the request but none was supplied.
DataIntegrityViolationException	The data sent in was not valid. You may see this error when trying to overwrite a value that cannot be overwritten.
InvalidFileFormat	The file format sent in was invalid.
InvalidError	The supplied value is not valid.
ObjectCannotBeSaved	There was an error saving the object.
InsufficientPermissions	The supplied credentials do not have permission to access this resource.
SystemError	Unexpected exception.
UniquenessViolationError	You can only have one object with this ID. Usually seen when trying to create a new object with a `providerAccountId` or `providerProfileId` that already exists.
InvalidDateRange	The date range is not valid. Usually caused by a `fromDateTime` being after a `toDateTime`.

Next steps

Review Dates & Times if you receive date-range or time-zone validation errors.
Use Testing & Debugging Overview or Simulate Errors to test your client's error handling before calling resource APIs.
Return to Getting Started to choose the API family that matches your workflow.