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:

NameHTTP status codeMeaningWhat you should do
Bad Request400The request was invalid or malformedFrom the error message, find out what was wrong with your request
Unauthorized401The access token was missing or invalidObtain a new access token with OAuth, potentially refreshing your token if it had expired
Not Allowed403Not allowed to perform the action, usually due to lack of permission to read or modify the requested resource
Not Found404The requested resource was not foundConsider the resource to be non-existent, it either never existed or no longer exists
Method Not Allowed405The requested resource was valid, but not for the HTTP verb used
Unprocessable Entity422A validation error occurredSee 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 Error500Something broke on our sideWe've been alerted to the problem and will be looking into it
Service Unavailable503PocketSmith or a dependency are down temporarily for maintenanceTry 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"


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.