HTTP Status Codes

The HTTP status codes used by this API were implemented using the standards provided from the HTTP 1.1 specification RFC2616

200 - OK [GETs, PUTs, and DELETEs]

  • Entity body - The resource
  • Example - [GET] People/1

201 - Resource created [POST]

  • Response Header - Location will contain the canonical URI
  • Entity body - the new resource
  • Example - [POST] People

204 - No Content [POST, DELETE]

  • Response Header - Response message will contain the canonical URI of the resource that has been deleted or in the case of account creation will be blank.
  • Entity body - will be empty
  • Example - [DELETE] /People/1636208/Attributes/29717636

301 - Moved Permanently

  • Response Header - Location will contain the new permanent canonical URI
  • Entity body - will be empty
  • Example - [GET] People/1 has been merged and no longer exists the new URI is People/1

400 - Bad Request: There is an error on the client side.

  • Response Header - No modification
  • Entity body - Send back a message on why the request was bad
  • Example - Malformed XML fails to serialize on the server

401 - Unauthorized

  • Response Header - WWW-Authenticate : OAuth and the challenge or required parameter
  • Entity body - Optionally, a doc describing the failure
  • Example - missing OAuth credentials

403 - Forbidden - Failed authorization

  • Response Header - No modification
  • Entity body - explanation of why authorization failed
  • Examples:
    • OAuth credentials were good, however, the token used for the request was not valid or user associated with the token does not have rights to the resource
    • Consumer is using a 3rd party key and secret and tries to request Access Tokens using user credentials.
    • When the Consumer Application can only accept requests for Tokens from the original provider or the Consumer Key for this application is either marked as Private or not accessible by the Tenant.

404 - Not Found: When a client requests a URI that does not map to a resource on the server

  • Response Header - No modification
  • Entity body - will be empty
  • Example - [GET] People/1 does not exist, optionally a 410 may be used (see below)

405 - Method not allowed

  • Response Header - Allow: GET, POST - list the HTTP methods the resource supports
  • Entity body - will be empty
  • Example - [POST] People/1/Status <- an attempt to create a status when only GET is available

406 - Not Acceptable

  • Response Header - Explanation of what made the request unacceptable
  • Entity body - will be empty
  • Example - Setting the Accept-Encoding header to an unknown type

409 - Conflict: Client tried to put the servers resource in an impossible or inconsistent state

  • Response Header - explanation of issue with status code
  • Entity body - will be empty
  • Example - Trying to add a Primary address to a resource that already has a primary address or PUT People/1 modifying "Weblink" credentials for People/1 that are already used by People/2

410 - Gone: server knew there used to be a resource but it's gone now

  • Response Header - HTTP/1.1 410 Entity is GONE because it has been deleted. Clients with link editing capabilities SHOULD delete references to the Request-URI.
  • Entity body - will be empty
  • Example - [DELETE] People/1/Addresses/1 then GET People/1/Addresses/1

415 - Unsupported Media Type

  • Response Header - Code detailed supported media types for the given resource
  • Entity body - will be empty
  • Example - Resource only supports XML and JSON, but the client sends application/atom+xm

500 - Internal Server Error

  • Response Header - No modification
  • Entity body - will be empty
  • Example - The server encountered an unexpected condition which prevented it from fulfilling the request.