Errors

The PocketSmith API provides proper HTTP status codes when errors happen. This helps inform the client of the nature of the error without having to examine the response body, which will contain an English error message.

These are the types of errors that should be anticipated from the PocketSmith API:

Name	HTTP status code	Meaning	What you should do
Bad Request	400	The request was invalid or malformed	From the error message, find out what was wrong with your request
Unauthorized	401	The access token was missing or invalid	Obtain a new access token with OAuth, potentially refreshing your token if it had expired
Not Allowed	403	Not allowed to perform the action, usually due to lack of permission to read or modify the requested resource
Not Found	404	The requested resource was not found	Consider the resource to be non-existent, it either never existed or no longer exists
Method Not Allowed	405	The requested resource was valid, but not for the HTTP verb used
Unprocessable Entity	422	A validation error occurred	See which field failed validation and remedy the issue. If the data was user-provided, show them the error and have them fix the data
Internal Server Error	500	Something broke on our side	We've been alerted to the problem and will be looking into it
Service Unavailable	503	PocketSmith or a dependency are down temporarily for maintenance	Try the request again at a later time

Every error listed above will have a JSON response body in the form:

{
  "error": "A nice English error message explaining the problem"
}

OAuth

Errors arising from OAuth will be spec-compliant, which means both an error and error_description field will be present in the response. In these cases, error will be some sort of identifier like invalid_credentials, where error_description will be an English explanation of the issue. To know if you're getting an error in OAuth format or a regular PocketSmith error, check for the presence of the error_description field.