Error handling

Invalid parameters or invalid requests return an error, server-side problems return an exception.

Errors

Errors are returned when an operation is invoked with wrong or missing arguments or without enough permissions.

Syntax

• error
  • errorId Fixed name of the error. You can test against this errorId to recover from known errors.
  • errorMessage Human message explaining the error

Error codes

These are some common errorId you may encounter:

• InsufficientLevel: You have called an API component which requires a higher authorization level. For example, you have called work.register with a GET authkey.
• InvalidNonceKey: Supplied nonce key is not correct
• InvalidParameter: Some parameter has an invalid value
• InvalidProtocol: You have called through HTTP a component that requires HTTPS
• InvalidRequest: The request has some invalid parameter or is not correct
• InvalidRestComponent: The specified component does not exist
• InvalidSignature: The request signature parameter is not correct
• InvalidTime: The request ztime parameter is not correct
• NotAuthorized: Your application is not authorized to perform this operation. For example, you are trying to get the state of an authkey not associated to your application.
• ProfessionalServiceNotActive: The operation you are requesting requires some professional service which the user has not purchased.
• RestParameterNotExpected: You have supplied a parameter not used by the component
• RestParameterNotFound: Some required parameter is missing
• UserKeyAuthNotFound: The provided authkey does not exist
• UserKeyNotFound: The provided sharedkey does not exist
• UserNotFound: The specified user code was not found
• WorkNotFound: The specified work code was not found

Example

REQUEST:

https://api.safecreative.org/v2/
?component=authkey.state
&sharedkey=zy9x4ol0ctg3btyswq7b5wi9
&ztime=1271749823276
&signature=c47b33222c850019574185051c3013ee817e5584

RESPONSE:

<?xml version="1.0" encoding="UTF-8"?>
<error>
  <errorId>RestParameterNotFound</errorId>
  <errorMessage>Required parameter not found: authkey</errorMessage>
</error>

Exceptions

Exceptions are returned if some unexpected error occurs in the API server. Exceptions are therefore not recoverable by your application. You should get in contact with Safe Creative if an exception persists.

Syntax

• exception
  • exceptionId Fixed name of the exception.
  • exceptionMessage Human message explaining the exception

Example

REQUEST:

https://api.safecreative.org/v2/?component=exception.test

RESPONSE:

<?xml version="1.0" encoding="UTF-8"?>
<exception>
  <exceptionId>RuntimeException</exceptionId>
  <exceptionMessage>This is a test exception</exceptionMessage>
</exception>