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 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 Socrta’s platform. Please let us know if you encounter a 500 error


For SODA 2.1 API calls, we include a few 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": "query.compiler.malformed",
  "error": true,
  "message": "Could not parse SoQL query \"select * where string_column > 42\"",
  "data": {
    "query": "select * where string_column > 42"

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