API: Reponse Codes and Errors

HTTP Status Codes

We try to follow the HTTP specification as closely as possible when returning status codes. This means we don't just use 200 and 404. The table below shows the codes returned and what they mean.

HTTP Code	Usage
200	Success. This is the most common response when everything works normally.
201	Created. This is returned when something is created, like a new wiki page.
204	No Content. The server has received the request and acted on it, but nothing needs to be returned. Often returned from a delete request.
400	Request Error. The most common error response. Something was wrong with the request. Inspect the error messages for more information.
403	Forbidden. You are not authorized to see the resource. Often returned when requesting a private campaign or a gm-only page. Inspect the error message for more information.
404	Not Found. The resource you requested cannot be found.
500	Server Error. An error happened on the server. If it continues, please notify us and we'll look into it.
503	Service Unavailable. The server is temporarily down for maintenance. We do this quite often, so we highly suggest building your apps to be prepared for it. Note: No guarantee that the response body will be a valid format (ie. JSON or XML) so it's best to look for the 503 and stop parsing if it's found.

Obsidian Portal Codes

In many cases, the HTTP status codes do not provide enough explanation. For some conditions, the API provides an additional code to better express what has occurred. These are not available for all errors. Instead, they are mainly available for common and recoverable error conditions.

Numerical Code	Name	Meaning
4010	INVALID_PARAMETER_VALUE	The passed parameter has an invalid value, such as an ill-formed e-mail address. Inspect the error message for more detail.
4020	CAMPAIGN_VISIBILITY_RESTRICTED	The requested campaign is not visible to you.
4030	GM_ONLY_RESOURCE	The requested resource is set to gm-only, and you are not the game master.
4040	CAMPAIGN_MEMBER_REQUIRED	The requested resource can only be modified by a campaign member.
4050	AUTHOR_OR_GM_REQUIRED	The requested resource can only be modified by the author or the GM.
4060	ASCENDANT_ONLY	The requested action is only available to Ascendant members.

Error Responses

Error responses all have the same format and are easy to distinguish from success responses. They are always accompanied by an HTTP error code (4xx or 5xx).

The error response is an array of errors, most often a 1-element array, with a message and optional error code. In addition, the HTTP status code is also included, in case the client is operating in an environment where this cannot be determined (ie. certain Flash and Javascript environments).

Example Error Response

The response below is an example of an error response to a JSON request to update a wiki page.

{
 'errors' : [
  {
   'message' : 'Name cannot be blank',
   'code' : 4010
  },
  {
   'message': 'Name is too short. 1 character minimum',
   'code' : 4010
  }
 ],
 'http_status' : 400
}
			

Remember: All errors will have a message, but not all will have a code.