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.