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.
If API runs into an error in its execution, it returns two different values with the result:
This is a verbose error message that tells what the error is.
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'.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
If language is sent with the request, then this error message is thrown when the defined language cannot be found in the system.
This message is returned if API version number is not allowed (not enabled in configuration file).
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.
This error message means that the server or browser is not compatible with the API Wrapper.
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.
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.
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
This means that the GET request has failed.
This means that the POST request has failed.
This means that API Wrapper has been unable to decrypt the data sent by the server in response.
This error means that API Wrapper has been unable to unserialize the data sent by the server.
This means that while API Wrapper requested validation timestamp or hash, server did not return the value. This is a security error.
This error means that the returned validation timestamp is considered too old by the API Wrapper.
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.
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.
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.
This means that Wrapper cannot serialize data for requests properly. Error message gives more information.
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.
This means that callback method was not found after the request, despite being defined.
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 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 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 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.