Error codes

Errors are per JSON-RPC 2.0 specification returned through the error object.

There is an exception though. The basic zipcode() and extended zipcode() functions return the combined results of multiple backend calls. A single backend error would therefore suppress the valid results from the other providers. To alleviate this these two functions may return errors inline with the other results in their error keys.

List of errors

001 Undocumented Error, please report to Nextpertise and refer to cid: %s.
This error message indicates that something happened that we didn’t anticipate. By reporting this incident to Nextpertise, mentioning the cid (correlation id) we may be able to resolve this and provide a better error message in the future.
002 Invalid zipcode/housenr combination: (%s,%d,%s).
The given zipocde, house number, house number extension is not recognized as a valid combination. Use the The Postcodes API functions to select a valid combination.
003 Service not available at this address: (%s,%d,%s).
The given address is valid but the provider does not service this address. This is most likely due to infrastructural constraints that will not change in the foreseeable future.
004 Service temporarily not available at this address (%s,%d,%s).
The given address is valid but the provider cannot service this address or offer any information about it. This is must likely due to a temporary disruption in the backoffice system of the provider.
005 User is not authorised to order (%s).
The user is not authorised to order product %s. By contacting Nextpertise we can discuss your options for future orders.
006 Failed to create requested (%s).

Something went wrong during the creation of %s. This error can occur due to multiple reasons, for instance:

  • The (%s) already exists.
  • Prerequisites don’t exist.
  • To create an mailbox, a client must exist already. (create_mailbox())
  • To create a forwarder, the email can’t exist yet as mailbox. (create_forwarder())
007 Failed to delete requested (%s).

Something went wrong during the deletion of (%s). As of now, there is one main reason why this error occurs, i.e.:

  • The (%s) does not exist.
008 Failed to update requested (%s).

Something went wrong while updating (%s). As of now, there is one main reason why this error occurs, i.e.:

  • The (%s) does not exist.
010 Connection too complex for this version of the software. Please contact Nextpertise.

This error may occur when requesting a zipcode check on KPN WBA on an address that KPN has labeled a ‘Complex Address’.

Eventually we expect to be able to handle this situation in the API but for now the only recourse is to contact Nextpertise.

011 JSON-RPC request or reply does not comply with its schema.

This error may occur when posting an invalid request to the API, but also when the API returns an invalid response. Nextpertise’s internal APIs are also validated against schemas so the error may have been generated in an internal API call trying to satisfy the initial request.

You can verify that the request you issue validates against the published schema for the API call. If you are certain your request is valid please contact Nextpertise so that we can resolve the problem.

012 Config Prohibited Error.
This error occurs when a user tries to perform an action it is not authorized to. Contact your employer if you feel this is not right.

HTTP Error codes

When something goes wrong before the JSON-RPC engine can process the request you will get an HTTP error reply. You are most likely to encounter:

401 Unauthorized

You tried to access a resource for which you are not authorized:

curl -v -u 'user:pass' https://api.nextpertise.nl/postcodes/v1 -d '{}'| jq .

produces:

> POST /postcodes/v1 HTTP/1.1
> Content-Length: 2
> Content-Type: application/x-www-form-urlencoded
>
< HTTP/1.1 401 Unauthorized
< Server: Zato
< Date: Wed, 07 Jun 2017 09:05:54 GMT
< Connection: close
< Transfer-Encoding: chunked
< X-Zato-CID: a3ad520ed60d2bb43df7ada9
< WWW-Authenticate: zato
<
{
    "zato_env": {
        "details": "You are not allowed to access this resource",
        "result": "ZATO_ERROR",
        "cid": "a3ad520ed60d2bb43df7ada9"
    }
}
404 Not Found

You tried to access a resource that doesn’t exist:

curl -v -u 'user:pass' https://api.nextpertise.nl/flup

produces:

> GET /flup HTTP/1.1
>
< HTTP/1.1 404 Not Found
< Server: Zato
< Date: Wed, 07 Jun 2017 09:01:00 GMT
< Connection: close
< Transfer-Encoding: chunked
< X-Zato-CID: c4caf1aa8a13cd8602fda301
<
[c4caf1aa8a13cd8602fda301] Unknown URL:[/flup] or SOAP action:[]
405 Method Not Allowed

You did not use the POST verb in the HTTP request:

curl -v -u 'user:pass' https://api.nextpertise.nl/broadband/v1 | jq .

produces:

> GET /broadband/v1 HTTP/1.1
>
< HTTP/1.1 405 Method Not Allowed
< Server: Zato
< Date: Wed, 07 Jun 2017 09:15:43 GMT
< Connection: close
< X-Zato-CID: 07c38f1c1311270f9be00765
<
{
    "zato_env": {
        "details": "Method `GET` is not allowed here",
        "result": "ZATO_ERROR",
        "cid": "07c38f1c1311270f9be00765"
    }
}