Response Codes & Headers

Response Codes

The Socrata Open Data API responds with standard HTTP Status Codes for both successful requests and for errors. The table below lists the response codes you should expect to see.

Code	Error	Description
200	`OK`	Your request was successful
202	`Request Processing`	You can retry your request, and when it’s complete, you’ll get a `200` instead
400	`Bad Request`	Probably your request was malformed. See the error message in the body for details
401	`Unauthorized`	You attempted to authenticate but something went wrong. Make sure you follow the instructions to authenticate properly
403	`Forbidden`	You’re not authorized to access this resource. Make sure you authenticate to access private datasets
404	`Not Found`	The resource requested doesn’t exist
429	`Too Many Requests`	Your client is currently being rate limited. Make sure you’re using an app token
500	`Server Error`	Our bad! Something has gone wrong with Socrata’s platform. Please let us know if you encounter a `500` error

Headers

For SODA 2.1 API calls, we include a few response headers that may be useful:

Header	Example	Description
`X-Socrata-RequestId`	`aqe1bgaxzvhitfgrsvy6semhi`	A unique ID for this particular request. Very useful to include when asking for help, as it allows us to track your error down in our system
`Access-Control-Allow-Origin`	`*`	Allows browsers to make cross-origin requests for data
`X-SODA2-Fields`	`["business","category", ...]` (truncated)	An array of the field names that may be included in this response
`X-SODA2-Types`	`["text","text",...]` (truncated)	An array of the data types for fields included in this response
`Last-Modified`	`Tue, 24 Feb 2015 18:51:22 GMT`	When the dataset backing this request was updated; may be used for caching
`ETag`	`"YWxwaGEuNTQzNV8...-gzip"` (truncated)	An HTTP ETag which may be used for cache validation

There may be other headers included in responses, but they should not be relied upon and may change without notice.

HTTP Headers are limited by practical constraints to a maximum size of 4K. In order to keep our request header sizes below that limit, the X-SODA2-Fields and X-SODA2-Types headers may be omitted for datasets with a very large number of columns.

Error Messages

For any variety of error, we return a standard error message format that looks like the following:

 {
  "code" : "soql.analyzer.typechecker.type-mismatch",
  "error" : true,
  "message" : "Type mismatch: expected text, but found number",
  "status" : 400,
  "data" : {
    "found" : "number",
    "expected" : [ "text" ]
  },
  "source" : {
    "position" : {
      "column" : 30,
      "row" : 1,
      "text" : "select * where string_column > 42"
    },
    "type" : "anonymous"
  }
}

In particular:

code: An enumeration for the particular class of error you have encountered
error: A boolean flag you can check in your code if your library masks the HTTP error code. Ex: if(response.error) { // handle error }
message: A human-readable error message that will help you debug what caused the error
data: Machine-readable data about the error, most importantly the query generated by our SoQL parser based on your inputs