Troubleshooting API Connections

This article walks through the most common causes of OpenSRS domain and trust API connection failures, and how to fix them. Start with the basic checks (API key, account permission, IP allow list) and move on to the advanced checks (MD5 authentication, port access, response codes) only if the basics look correct.

Before you begin

• You can sign in to the OpenSRS Reseller Control Panel (RCP) as the primary reseller user.
• You know the public IP address of the server or workstation making the API call.
• You have shell access to the calling host so you can run curl, ping, traceroute, and openssl.

Basic checks

Verify the API key

The API key lives in the RCP under Account settings → API settings. Confirm the key your client is using matches what is shown there.

1. Log in to the RCP.
2. Click Account settings in the top right.
3. Select the API settings tab. The key is at the top of the API key section.

Verify reseller account permission

The username you send must be the primary reseller username on your account in the environment you are connecting to (live or test). Sub-users cannot authenticate to the API. See the sub-user reference for details.

Verify the IP allow list

The device making the call must use an IP address that you have explicitly allowed.

1. Log in to the RCP.
2. Click Account settings.
3. Open the API settings tab. The IP access rules section appears below the API key section.
4. Confirm the calling host's public IP matches one of your Allow rules.

Advanced checks

Check the MD5 authentication

If the key, user, and IP all look correct but you still get authentication errors, the problem is usually how the MD5 signature is being calculated. Verify each of the following:

• You have concatenated the XML content and the Private Key correctly.
• You have performed the MD5 hash twice. See the MD5 examples in the official documentation.
• Your HTTP POST implementation is not adding extra bytes. Some implementations append a NULL to the end of the request, which changes the hash and causes an authentication error.
• The MD5 result is in lowercase before you send it. Some algorithms return uppercase hashes.
• If your MD5 implementation requires you to convert the string to bytes, the conversion is being done correctly.

Test your MD5 routine against the following known input/output pair:

Verify port access

When you can authenticate but cannot reach the server (or vice versa), test connectivity from the calling host. You can email the output to OpenSRS Support for further troubleshooting.

Confirm your outbound IP:

curl http://icanhazip.com/s/
# or
wget -q -O - http://icanhazip.com/s/

Confirm DNS and basic reachability:

ping rr-n1-tor.opensrs.net

Trace the network path:

traceroute rr-n1-tor.opensrs.net

Test the TLS handshake on the API port:

openssl s_client -connect rr-n1-tor.opensrs.net:55443

Interpreting response codes

If you receive a response from OpenSRS but it indicates failure, look up the response code in the OpenSRS response codes reference. The code, paired with the response text, will usually tell you exactly what to fix.

Next steps

• If basic checks all pass but calls still fail, capture the raw request, the calculated MD5, and the response, then contact OpenSRS Support with that bundle.
• If port tests fail, check your firewall, security group, or NAT rules for outbound TCP 55443.
• If response codes point to a business-rule problem (for example, balance, TLD eligibility), consult the relevant API command reference rather than the connection guide.

Questions? Contact OpenSRS Support.