Responses

Use this page to understand Signal API response formats, HTTP status codes, response payloads, and error handling.

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

HTTP status code: Protocol-level status of the response.
Response payload: Response body in a standard format that provides application-level status, results, and errors.

Response formats

All responses are returned in JSON format.

HTTP status codes

Signal APIs use standard HTTP status codes to indicate success or failure.

HTTP Code	Message	Description
`200`	OK	The request was processed and returned successfully.
`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 the rate limit was exceeded.
`404`	Not Found	The URL is incorrect, or the requested resource does not exist.
`500`	Server Error	A problem occurred while handling the request.
`503`	Service Unavailable	The API is temporarily unavailable.

Response payload

Each API response is wrapped in a standard payload that contains results and useful metadata such as total record count and result object type.

{
  "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
    }
  ]
}

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

Results are returned as an array, even when requesting a single object.

Response payload changes

New fields may be added to responses over time. API clients should be prepared to ignore object properties they do not recognize.

Errors

Errors are communicated in the response payload.

{
  "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"
    }
  ]
}

The Error type includes these fields:

Name	Type	Description
`code`	String	Unique string identifying the error type.
`message`	String	Localized, user-readable message describing the error.
`objectName`	String	Object type related to the error.
`propertyName`	String	Object property related to the error.