Errors

HTTP Error codes

The following HTTP error codes can be returned by the APIO.

Code	Text	Description
200	Ok	Success!
201	Created	The entity has been successfully created.
207	Multi-Status	The operation has only partially succeeded.
304	Not modified	There was no new data to return.
400	Bad Request	The request was invalid or cannot be otherwise served. An accompanying error message will explain further. Requests with invalid parameters will yield this response.
401	Unauthorized	Missing or incorrect authentication credentials.
403	Forbidden	The request is understood, but it has been refused or access is not allowed.
404	Not Found	The URI requested is invalid or the resource requested, such as a user, does not exists.
406	Not Acceptable	Returned when an invalid format is specified in the request.
410	Gone	This resource is gone. Used to indicate that an API endpoint has been turned off.
416	Bad Media Type	When the HTTP Body is not a JSON object or empty
422	Unprocessable Entity	Returned when a (batch) file uploaded is unable to be processed.
429	Too Many Requests	Returned when a request cannot be served due to the application’s rate limit having been exhausted for the resource.
500	Internal Server Error	Something is broken. Please post to the developer forums with additional details of your request, so the Netaxis team can investigate.
502	Bad gateway	The API gateway is down or being upgraded.
503	Service Unavailable	The API gateway servers are up, but overloaded with requests. Try again later.
504	Gateway timeout	The API gateway servers are up, but the request couldn’t be serviced due to some failure within our stack. Try again later.

This table is in constant evolution during the life cycle of the product.

Error messages

When the APIO returns error messages, it does so in JSON. The body contains either a “details” attribute or a list of error objects containing:

• A code as a number (See Error codes).

• A message (optional) as an informative indication about the error.

• A details object (optional) holding some extra information which depend of the error code returned.

For example, an error might look like this:

{
   "errors": [
      {
         "message": "Sorry, that page does not exist",
         "code": 34
      }
   ]
}

or

{"details": "This method is not allowed."}

Note

This format is used as return for http error codes: 405, 404, (tbc…)

Error codes

In addition to descriptive error text, error messages contain machine-parseable codes. While the text for an error message may change, the codes will stay the same.

Each API can return any of the error codes described below (and most often the JSON_SCHEMA_VALIDATION_ERROR, the UNAUTHENTICATED and INVALID_PARAMETERS). Some API can be more likely to return a specific error code due to its logic. In that case that error code could be explicitly mentioned in the API definition with a more precise description of the error in that context. But all the other eror codes could of course still occur if relevant.

The following table describes the codes that may appear when working with the API:

Code	Text	Description
0	GENERIC	Internal server error.
1	MISSING_MANDATORY_PARAMETERS	Missing mandatory parameters.
2	INVALID_PARAMETERS	Invalid parameters provided.
3	JSON_SCHEMA_VALIDATION_ERROR	Received data do not respect the schema. See JSON Schema Validation Error Structure for details.
4	UNAUTHENTICATED	Need to be authenticated.
5	NO_NE_AVAILABLE	No Network Element associated to your session, please reconnect. Either you are not allowed to access the NE needed for this API or your session is lost
6	ERROR_RETURNED_BY_NE	Network Element reported an error.
7	UNAUTHORIZED_BY_NE	Network Element unauthorized the request.
8	NOT_FOUND_AT_NE	Network Element do not know this element.
9	MISSING_CONDITIONAL_PARAMETERS	Missing conditional parameters.
10	INVALID_PHONE_NUMBER	Invalid format for the phone number.
11	ALREADY_EXISTS	The resource already exists.
12	INVALID_EMAIL	Invalid Format for the email address.
13	INVALID_TIMEZONE	This timezone is not supported.
14	NOT_ALLOWED_NUMBER	This number does not belongs to this Group.
15	CANNOT_DELETE_YOURSELF	Cannot delete yourself.
16	NOT_AVAILABLE	The resource is not available.
17	CANNOT_MODIFY	Can not modify the resource.
18	INVALID_OPERATION	Operation not allowed.
19	NOT_AVAILABLE_FOR_ASSIGNMENT	Resource is not available for assignment.
20	NOT_ADDED	Resource can not be assigned.
21	NOT_DELETED	Resource can not be deleted.
22	INVALID_PORT_NUMBER	Invalid port number.
23	SERVICE_NOT_ASSIGNED	Service is not assigned to this subscriber.
24	INVALID_RESPONSE_SIZE_LIMIT	Size of search response is too big.
25	IS_DUPLICATED	Duplicate specified resource.
26	NO_MORE_LICENSES	The licensed number of users for the system has been reached.
27	INVALID_FILE_FORMAT	Invalid file format.
28	MISSING_INFORMATION_IN_PROFILE	Missing information in user profile.
29	CAN_NOT_DELETE_NON_EMPTY
30	STILL_IN_USE	The resource is still in use and can not be deleted.
31	UNABLE_TO_UPDATE_PHONE_VENDOR	Phone Provisioning Server reply with an error.
32	UNABLE_TO_UPDATE_PHONE_REDIRECT	Phone Redirect Server reply with an error.
33	PASSWORD_EXPIRED	Valid credentials provided but password is expired.
34	EMAIL_SENDING_ERROR	An error occurred during the sending of the email.
35	SSO_REFUSED	The OpenID server has refused the connection.
36	SSO_INVALID_GROUPID_AND_USERNAME	Failed to authenticate a user with the data returned by server.
37	SSO_INVALID_USERNAME	Invalid username returned by the OpenID server.
38	SSO_MULTI_GROUPS	More than one GroupIds returned.
39	SSO_INVALID	No TokenID received from the OpenID server or the nonce is not matching.
40	SSO_UNREACHABLE	OpenID server is not reachable.
41	BLOCKED_NUMBER	This number can not be used
42	NOT_AVAILABLE_IN_SP_MODE	Operation not allowed on a Service Provider.
43	IMPOSSIBLE_TO_GENERATE_ID	The rule to generate an id did not produce a valid result (for example missing field)
44	GENERATED_ID_ALREADY_EXISTS	The generated id is already existing and no random part allow to generate an other one
45	API_NOT_AVAILABLE_AT_NE	The Network Element does not offer this capability (could be due to its version)
46	NOT_AVAILABLE_IN_ENTERPRISE_MODE	Operation not allowed on an Enterprise.
47	SERVER_LICENSE_EXPIRED	The license of the Application Server has expired
50	CAN_NOT_DELETE_DUE_TO_NETWORK_INCONSISTENCY	A inconsistency at network level prevents to delete safely the asked resource
51	NOT_ALLOWED_PARAMETER	One parameter is not allowed to be present
52	FORBIDDEN_DELETE_REFERENCE_DATA	Forbidden to delete test reference data
53	INVALID_TYPE	This type of Call Center does not support the requested feature
54	CANNOT_DELETE	This requested resource can not be deleted
55	SERVER_BUSY	Thie Application Server is busy and can not threat the request. It has to be retried later.
56	UNSUPPORTED_OPERATION	The operation requested by the parameters is not supported by the end point
57	PARAMETER_NOT_SUPPORTED_FOR_NE_VERSION	The Network Element version does not support this parameter.
58	UNAUTHORIZED_PARAMETER_FOR_USER_LEVEL	The provided parameters are not authorized for this user level.
59	INVALID_CALL_OPERATION	The operation requested is not valid for that call.
60	CONFIGURATION_ISSUE	The operation requested can not be performed due to invalid configuration of the APIO.
61	NO_BACKEND_AVAILABLE	The backend requested for this request does not exist or is not in your profile
62	SCHEDULE_NOT_COMPATIBLE_SIMPLE_MODE	Schedule period not compatible with simplified mode
63	REMOTE_SERVER_ISSUE	When the triggered Network Element can not process the request without providing more info.
64	INVALID_DEVICE	The device asked can not be used/deleted in the context of the API call.
65	TOO_LARGE	Usually linked to an audio file too big to be accepted by the storage.

This table is in constant evolution during the life cycle of the product.

For example introduction of new features could result in new dedicated error codes.

Sub Error Codes for Phone Vendor

In case of errors occuring during the interactions with a Phone Vendor Provisioning Server (see Access Device Advanced Management) the error code will be UNABLE_TO_UPDATE_PHONE_VENDOR. In order to provide more details on the error, a field named sub_code is provided in most cases, with the following values:

Code	Text	Description
4001	INVALID_MAC	Invalid MAC address format
4002	MAC_ALREADY_IN_USE	MAC address already in use
4003	MAC_OWNER_BY_OTHER	Not the owner of the phone
4004	INVALID_DESTINATION_SERVER	This type of phone is not yet configured in the Phone Vendor, or invalid value in APIO Configuration
4005	MAC_NOT_FOUND	MAC address not found
4006	MAC_OVERRIDE_FAILED	Impossible to override the MAC address configuration
4007	VENDOR_SERVER_ERROR	Issue at Phone Vendor side
4008	MAC_NOT_FROM_VENDOR	MAC address not known by this Phone Vendor
4009	APIO_CONFIGURATION_ISSUE	Configured Phone Vendor Server credentials are invalid, or other configuration issue
4010	VENDOR_SERVER_NOT_REACHABLE	Phone Vendor Server is not reachable

This table is in constant evolution during the life cycle of the product.

JSON Schema Validation Error Structure

JSON schema errors has the following structure

{
   "errors": [
      {
         "code": 3,
         "message": "Received data do not respect the schema",
         "details": {
            "fields": [
               "name"
            ],
            "reason": "12345 is not of type 'string'"
         }
      }
   ]
}

• code: the error code. Most of the time will be JSON_SCHEMA_VALIDATION_ERROR.

• message: the generic error message.

• fields: the list of fields that failed the validation process.

• reason: the specific error message. Describes in detail why the validation has failed.

Invalid Parameters Error Structure

The invalid parameters errors are generated after the JSON shcema is checked.

They can be of 2 sources:

• APIO logic doing complex validation that can not be expressed at JSON schema level

• APIO logic applying additional constraints checks that are specific to the Network Element (an Application Server usually) that it will trigger to perform the requested action.

{
   "errors": [
      {
         "code": 2,
         "message": "Invalid value(s) for parameter(s)",
         "details": {
            "fields": ["insensitiveUserLastNameEquals"],
            "reason": "The length must be in range 1 and 30."
         }
      }
   ]
}

• code: the INVALID_PARAMETERS error code.

• message: the generic error message.

• fields: the list of fields that failed the validation process.

• reason: the specific error message. Describes in detail why the validation has failed.