diff --git a/bramble-api/src/main/java/org/briarproject/bramble/api/contact/ContactManager.java b/bramble-api/src/main/java/org/briarproject/bramble/api/contact/ContactManager.java
index f131a1d2f4b7337a9a6779b4d22bd5ec33740d99..75e61ccc1488f57989db6bc02fb98883f9a19512 100644
--- a/bramble-api/src/main/java/org/briarproject/bramble/api/contact/ContactManager.java
+++ b/bramble-api/src/main/java/org/briarproject/bramble/api/contact/ContactManager.java
@@ -1,8 +1,10 @@
 package org.briarproject.bramble.api.contact;
 
 import org.briarproject.bramble.api.FormatException;
+import org.briarproject.bramble.api.UnsupportedVersionException;
 import org.briarproject.bramble.api.crypto.SecretKey;
 import org.briarproject.bramble.api.db.DbException;
+import org.briarproject.bramble.api.db.NoSuchContactException;
 import org.briarproject.bramble.api.db.Transaction;
 import org.briarproject.bramble.api.identity.Author;
 import org.briarproject.bramble.api.identity.AuthorId;
@@ -65,10 +67,15 @@ public interface ContactManager {
 	String getHandshakeLink() throws DbException;
 
 	/**
-	 * Adds a new pending contact identified by the given handshake link.
+	 * Creates a {@link PendingContact} from the given handshake link and
+	 * alias, adds it to the database and returns it.
 	 *
-	 * @param link The handshake link received from the contact we want to add.
-	 * @param alias The alias the user has given this contact.
+	 * @param link The handshake link received from the contact we want to add
+	 * @param alias The alias the user has given this contact
+	 * @return A PendingContact representing the contact to be added
+	 * @throws UnsupportedVersionException If the link uses a format version
+	 * that is not supported
+	 * @throws FormatException If the link is invalid
 	 */
 	PendingContact addPendingContact(String link, String alias)
 			throws DbException, FormatException;
@@ -92,7 +99,7 @@ public interface ContactManager {
 	 * Returns the contact with the given remoteAuthorId
 	 * that was added by the LocalAuthor with the given localAuthorId
 	 *
-	 * @throws org.briarproject.bramble.api.db.NoSuchContactException
+	 * @throws NoSuchContactException If the contact is not in the database
 	 */
 	Contact getContact(AuthorId remoteAuthorId, AuthorId localAuthorId)
 			throws DbException;
@@ -101,7 +108,7 @@ public interface ContactManager {
 	 * Returns the contact with the given remoteAuthorId
 	 * that was added by the LocalAuthor with the given localAuthorId
 	 *
-	 * @throws org.briarproject.bramble.api.db.NoSuchContactException
+	 * @throws NoSuchContactException If the contact is not in the database
 	 */
 	Contact getContact(Transaction txn, AuthorId remoteAuthorId,
 			AuthorId localAuthorId) throws DbException;
diff --git a/bramble-core/src/main/java/org/briarproject/bramble/contact/PendingContactFactory.java b/bramble-core/src/main/java/org/briarproject/bramble/contact/PendingContactFactory.java
index eab17d59d5cf21443fb006315ddd79ac66e59f78..cfa5555655a6ea86e64cb91e3d4a4fbf94099c70 100644
--- a/bramble-core/src/main/java/org/briarproject/bramble/contact/PendingContactFactory.java
+++ b/bramble-core/src/main/java/org/briarproject/bramble/contact/PendingContactFactory.java
@@ -1,10 +1,18 @@
 package org.briarproject.bramble.contact;
 
 import org.briarproject.bramble.api.FormatException;
+import org.briarproject.bramble.api.UnsupportedVersionException;
 import org.briarproject.bramble.api.contact.PendingContact;
 
 interface PendingContactFactory {
 
+	/**
+	 * Creates a {@link PendingContact} from the given handshake link and alias.
+	 *
+	 * @throws UnsupportedVersionException If the link uses a format version
+	 * that is not supported
+	 * @throws FormatException If the link is invalid
+	 */
 	PendingContact createPendingContact(String link, String alias)
 			throws FormatException;
 }
diff --git a/bramble-core/src/main/java/org/briarproject/bramble/contact/PendingContactFactoryImpl.java b/bramble-core/src/main/java/org/briarproject/bramble/contact/PendingContactFactoryImpl.java
index 4e4ac278287fd90c799139506c8c21443e320b0e..1b7b149ea12f46c44f1b41e7cfda82818498e821 100644
--- a/bramble-core/src/main/java/org/briarproject/bramble/contact/PendingContactFactoryImpl.java
+++ b/bramble-core/src/main/java/org/briarproject/bramble/contact/PendingContactFactoryImpl.java
@@ -1,6 +1,7 @@
 package org.briarproject.bramble.contact;
 
 import org.briarproject.bramble.api.FormatException;
+import org.briarproject.bramble.api.UnsupportedVersionException;
 import org.briarproject.bramble.api.contact.PendingContact;
 import org.briarproject.bramble.api.contact.PendingContactId;
 import org.briarproject.bramble.api.contact.PendingContactState;
@@ -49,7 +50,9 @@ class PendingContactFactoryImpl implements PendingContactFactory {
 		if (link.startsWith("briar://")) link = link.substring(8);
 		byte[] base32 = Base32.decode(link, false);
 		if (base32.length != RAW_LINK_BYTES) throw new AssertionError();
-		if (base32[0] != FORMAT_VERSION) throw new FormatException();
+		byte version = base32[0];
+		if (version != FORMAT_VERSION)
+			throw new UnsupportedVersionException(version < FORMAT_VERSION);
 		byte[] publicKeyBytes = new byte[base32.length - 1];
 		arraycopy(base32, 1, publicKeyBytes, 0, publicKeyBytes.length);
 		try {