General

I need a prefix for my test environment?

PIDs are meant to be a permanent reference to an object. All PIDs made under your prefix are meant to be kept forever and tombstoned if the object no longer exists or reference is no longer valid. We can however offer you access to a special test prefix. This dummy prefix allows you to test all of your tools and integrations and any PIDs "minted" under this test prefix will be deleted. Please reach out to our service portal if you would like access this.

Who owns the PIDs?

Generally the creator or minter of the PID is the owner and responsible for maintaining and updating the PID. Your institution may opt to regulate this slightly differently for your specific use case but SURF takes no responsibility for the content of your PIDs. We also recommend drafting a policy for the smooth transfer of ownership of PIDs should the current owner move institutions, retire or no longer be available to maintain the PID.

I am suddenly no longer able to access the service using the API?



There are two possible explanations for this, our service is down or your IP has been banned. 



To check whether the service is up and running, you can check our Service Status page.



If you (or someone using the same IP address) tried 3 times in a row to resolve a prefix that we do not host using our API, they may have been banned. We do this to prevent malicious actors from attacking the service. If you would like to resolve a PID but you aren’t sure where it’s hosted, we recommend using the global resolver and your web browser. If you forgotten your prefix, please create a ticket in the service portal and we’d be happy to remind you. If this was the result of a bug in a script, please fix your API calls and create a ticket in the service portal stating your problem and IP address and we can manually remove the ban.

Common error messages

When I try to mint I get the error message "that prefix doesn't live here"?

If you get a response like:

{"responseCode":301,"message":"That prefix doesn't live here","handle":"<prefix>/<suffix>"} 

you are most likely trying to contact the incorrect instance server or using the wrong port. Please check the information that was provided to you by SURF.

When I use curl I get the error message "SSL: Can't load the certificate "/<path>/<cert>.pem" and its private key: OSStatus -25299"?

Your version curl wasn't compiled with OpenSSL support. See the appropriate Handle API user documentation under Using the Service for instructions on how to compile curl correctly within your system.

I keeping getting the HTTP 401 or 402 error messages?

This error can occur if the username does not have admin permissions yet. Make sure it is referred to in HS_ADMIN or HS_VLIST with admin permissions. This error can also occur if the username did not get permissions for the specific handle in its HS_ADMIN entry. Each user can only modify handles whose HS_ADMIN entry (or one of its HS_ADMIN entries) gives write permissions to him, either directly or by pointing to a HS_VLIST that has admin permissions and that contains the username.

I keep getting a "SSL handshake failure" error message?

Check that your private key isn't encrypted and that you're using an OpenSSL version of 1.0.1 or newer.

I keep getting a "PEM lib" error message?

This error occurs if the private key was not provided or put into the same file as the certificate. For this reason we advise placing the certificate and private key in two separate files.