Responses & Errors

Responses

All responses will look roughly like

        {
          "meta": {
            "code": 200,
             ...errorType and errorDetail...
          },
          "notifications": {
             ...notifications...
          },
          "response": {
             ...results...
          }
        }
        

The errorType is detailed information intended for the application developer. We ask applications to show an appropriate error to their users by handling the error codes listed below. We will add additional types as needed. The deprecated type may be returned even if a request is successful.

The meta section may also contain a message which provides additional information intended to help developers debug problems.

Certain requests may also contain notifications as a top-level item based on a just-submitted checkin or other user actions.

To use JSONP, add a callback=XXX parameter to your request and we will respond with XXX(response). In the case of JSONP, we always return 200 (except in the case of 500’s) so the brower will allow the response to be handled by your code, but the true HTTP response code can be obtained from the code in the meta response.

Errors

As much as possible, foursquare attempts to use appropriate HTTP status codes to indicate the general class of problem, and this status code is repeated in the code section of the meta response.

400 (Bad Request) Any case where a parameter is invalid, or a required parameter is missing. This includes the case where no OAuth token is provided and the case where a resource ID is specified incorrectly in a path.
401 (Unauthorized) The OAuth token was provided but was invalid.
403 (Forbidden) The requested information cannot be viewed by the acting user, for example, because they are not friends with the user whose data they are trying to read.
404 (Not Found) Endpoint does not exist.
405 (Method Not Allowed) Attempting to use POST with a GET-only endpoint, or vice-versa.
409 (Conflict) The request could not be completed as it is. Use the information included in the response to modify the request and retry.
500 (Internal Server Error) Foursquare’s servers are unhappy. The request is probably valid but needs to be retried later.

Additional details are provided in the errorType. It should be one of the following.

errorType Status Code Explanation
invalid_auth 401 OAuth token was not provided or was invalid.
param_error 400 A required parameter was missing or a parameter was malformed. This is also used if the resource ID in the path is incorrect.
endpoint_error 404 The requested path does not exist.
not_authorized 403 Although authentication succeeded, the acting user is not allowed to see this information due to privacy restrictions.
rate_limit_exceeded 403 Rate limit for this hour exceeded.
deprecated 200 Something about this request is using deprecated functionality, or the response format may be about to change.
server_error Varies Server is currently experiencing issues. Check status.foursquare.com for updates.
other Varies Some other type of error occurred.

Errors will usually include an errorDetail field with additional information about what went wrong, intended for the developer. In some cases, the server may include an errorMessage, which is a localized string intended for the client to display back to the user directly.