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.

Headers

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

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