API Response Codes

Introduction

There are very few times when using API will cause it to fail with a fatal error. In most cases API commands will return data just like they would when no error is encountered, except it can carry information about the problem encountered or details about what went wrong.

For this reason, Wave Framework implements four categories of response codes, 1XX response codes that are for internal errors, 2XX response codes that are reserved for API Wrappers, 3XX which is reserved for custom error response codes and 4XX which is reserved for custom return message response codes defined by the developer.

1XX - Native API Response Codes

If API runs into an error in its execution, it returns two different values with the result:

www-error

This is a verbose error message that tells what the error is.

www-response-code

This is the error code of the message. This can be used by other systems to easily detect what error the system ran into without having to parse or rely on verbose error message of 'www-error'.

100 - Server configuration error

This error means that there is nothing you can do as a developer and the problem lies in server configuration. You should change PHP settings, upgrade software or tweak other aspects of the server. If you are unable to do that, then you should contact server administrator for further assistance.

101 - API command not set

This message is thrown when 'www-command' was missing from the API request. This variable is required for Wave Framework API to know what controller and method is being requested.

102 - API public requests require a public request token

This means that the API request, which used public API profile, did not provide a public request token. Either the token was not added to the request or was incorrect. Public request tokens protect the website from cross-site-request-forgeries.

103 - API profile not found

API profile that is used with the request (sent as 'www-profile') was not found in the API profiles file. You should double-check to make sure this profile actually exists.

104 - API profile is disabled

This error message means that while the API profile does exist in the system, it is currently disabled and you should either change the setting in API profiles file, or ask the API owner to change this setting.

105 - API profile not allowed from this IP

This error means that the IP, where the request is made from, is not allowed and that the API profile that is used has only specific allowed IP's defined in API profiles file.

106 - API command is not allowed for this profile

This error means that while API profile is correct, the requested 'www-command' is not allowed to be called with this API profile. This is a permissions problem.

107 - API request validation timestamp is missing

This error message means that the current API profile requires that you send a 'www-timestamp' of the time you made the request for validation purposes.

108 - API request timestamp is too old

This error message means that the sent www-timestamp was too old for the responding server and the server considers it insecure to return a response to the request.

109 - API profile configuration incorrect

This means that there's a problem with API profile configuration, that is being used. This usually means that the secret key or certificate is missing.

110 - API request validation hash is missing

This error means that the server needs to validate the input data and the validation hash that is used for this purpose, sent with 'www-hash', was missing.

111 - API session token does not exist or is timed out

This error means that the session token, which is used to validate API requests, does not exist anymore or has timed out and a new token should be generated.

112 - API profile authentication failed

This error message means that the API profile input hash validation or token authentication failed, which means that either the validation calculation is incorrect or the data has been tampered with or that the token was incorrect. This is a security error.

113 - API session token commands cannot be used with public profile

Public API's cannot create validation tokens (though their requests can create regular sessions and cookies). This error is returned when it is attempted to create a token with a public profile.

114 - Problem decrypting encrypted data

If encrypted data was sent to the server, then this error message means that the server was unable to decrypt this encrypted data and is unable to proceed.

115 - API request recognized, but unable to handle

This error means that the 'www-command' sent to the server cannot be properly handled and usually means that the controller or the method does not exist.

116 - Language cannot be found

If language is sent with the request, then this error message is thrown when the defined language cannot be found in the system.

117 - API version cannot be used

This message is returned if API version number is not allowed (not enabled in configuration file).

2XX - API Wrapper Response Codes

API Wrappers can return all error codes from all namespaces, but if the returned error code is 2XX, then the error message comes internally from API Wrapper, rather than Wave Framework API itself.

API Wrappers store the last error code and error message as 'responseCode' and 'errorMessage' variables. These should be checked if the request returns false.

200 - Client configuration error

This error message means that the server or browser is not compatible with the API Wrapper.

201 - API command is not set, this is required

This is similar to 101 error, except thrown by API Wrapper. This means that the API command was not set prior to sending the request.

202 - Crypted input can only be used with a set secret key

This error message means that crypted input was set prior to sending a request, but secret key was not, so API Wrapper is unable to actually encrypt the data.

203 - Unable to encrypt data, server configuration problem

This error message means that API Wraper was unable to encrypt the data that was assigned to be encrypted. This usually means that PHP does not have classes or methods for generating Rijndael 256bit encryption

204 - GET request failed

This means that the GET request has failed.

205 - POST request failed

This means that the POST request has failed.

206 - Output decryption has failed

This means that API Wrapper has been unable to decrypt the data sent by the server in response.

207 - Cannot unserialize returned data

This error means that API Wrapper has been unable to unserialize the data sent by the server.

208 - Validation data missing

This means that while API Wrapper requested validation timestamp or hash, server did not return the value. This is a security error.

209 - Validation timestamp is too old

This error means that the returned validation timestamp is considered too old by the API Wrapper.

210 - Validation state keys do not match

This error means that the originally sent www-state does not match the returned www-state, thus it might be that the communication has been tampered with. This is a security error.

211 - Hash validation failed

This error means that API Wrapper was unable to validate the data sent by the server and the hash API Wrapper found is different from the one sent by the server. This is a security error.

212 - Cannot make URL requests

This means that Wrapper is unable to make requests and this is likely a system problem. Error message gives more information. This error is PHP wrapper-specific.

213 - Cannot serialize data

This means that Wrapper cannot serialize data for requests properly. Error message gives more information.

214 - Not modified

This is returned if server founds that data has not been modified since last request. Essentially this is the error message for HTTP 304 status codes.

215 - Form not found

This means that the submit form was not found, this error is JavaScript wrapper-specific.

216 - Callback method not found

This means that callback method was not found after the request, despite being defined.

217 - JSONP/JSONV cannot be used to submit a form

This JavaScript API Wrapper specific error is returned when JSONP/JSONV is used together with defined form.

218 - JSONP/JSONV cannot be used for POST requests

This JavaScript API Wrapper specific error is returned when JSONP/JSONV is used while making a POST request. Usually this means that there is too much data being sent.

Custom Error Code Namespaces 3XX/4XX/5XX

It is not necessary to return specific error codes from controllers, but Wave Framework API comes with helper functions to format proper error messages in an array that can be expected as a response by systems that communicate with Wave Framework API.

For this purpose, it is recommended to return data in expected format, with the response codes added to the response.

3XX - Custom Error Codes

3XX namespace is meant for service specific errors, for cases when things did not go at all how it was expected. 3XX namespace is meant for developer of the system to use freely and document by themselves. 3XX errors are covered in debugger logs as well.

4XX - Custom Failed Response Codes

4XX namespace is meant for service specific responses that are considered failed or false, for cases when the API command failed for one reason or another. 4XX namespace is meant for developer of the system to use freely and document by themselves. 4XX namespace does not throw errors in debugger log and are only service specific.

5XX - Custom Success Response Codes

5XX namespace is meant for service specific responses that are considered successful, for cases when the API command succeeded and likely worked the way request-initiator expected. 5XX namespace is meant for developer of the system to use freely and document by themselves.