Throw exceptions when something goes wrong instead of returning null

src/Exception/ApiErrorException.php

@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pcm\GeocodeBundle\Exception;
+
+class ApiErrorException extends GeocodeException
+{
+}
+

src/Exception/GeocodeException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pcm\GeocodeBundle\Exception;
+
+class GeocodeException extends \RuntimeException
+{
+    public function __construct(string $postcode, string $message)
+    {
+        $formattedMessage = sprintf("Failed to geocode a postcode \"%s\": %s", $postcode, $message);
+
+        parent::__construct($formattedMessage);
+    }
+}
+

src/Exception/NoResultsFoundException.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Pcm\GeocodeBundle\Exception;
+
+class NoResultsFoundException extends GeocodeException
+{
+    private const string MESSAGE = "No results found.";
+
+    public function __construct(string $postcode)
+    {
+        parent::__construct($postcode, self::MESSAGE);
+    }
+}
+

src/Service/Geocoder.php

@@ -4,6 +4,8 @@ declare(strict_types=1);
 
 namespace Pcm\GeocodeBundle\Service;
 
+use Pcm\GeocodeBundle\Exception\ApiErrorException;
+use Pcm\GeocodeBundle\Exception\NoResultsFoundException;
 use Pcm\GeocodeBundle\Model\GeoCoordinates;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
 use Symfony\Contracts\HttpClient\ResponseInterface;
@@ -26,13 +28,12 @@ final class Geocoder
         $response = $this->makeApiRequest($client, $postcode);
         $data = $this->getDataFromResponse($response);
 
-        // @todo remove check, I don't think it's needed
-        if (empty($data)) {
-            return null;
+        if (array_key_exists('error', $data)) {
+            throw new ApiErrorException($postcode, $data['error']['message']);
         }
 
-        if (array_key_exists('error', $data)) {
-            return null;
+        if (empty($data)) {
+            throw new NoResultsFoundException($postcode, "No results found.");
         }
 
         return $this->createGeoCoordinates($data);

tests/Service/GeocodeTest.php

@@ -6,6 +6,8 @@ namespace Pcm\GeocodeBundle\Tests;
 
 use Pcm\GeocodeBundle\Entity\Interface\MappableInterface;
 use Pcm\GeocodeBundle\Entity\Trait\MappableTrait;
+use Pcm\GeocodeBundle\Exception\ApiErrorException;
+use Pcm\GeocodeBundle\Exception\NoResultsFoundException;
 use Pcm\GeocodeBundle\Model\GeoCoordinates;
 use Pcm\GeocodeBundle\Service\Geocoder;
 use Pcm\GeocodeBundle\Tests\AppKernel;
@@ -33,10 +35,20 @@ final class GeocodeTest extends KernelTestCase
         $this->assertInstanceOf(Geocoder::class, $this->geocoder);
     }
 
-    public function testGeocodePostcodeReturnsNullOnInvalidInput(): void
+    public function testGeocodePostcodeThrowsOnEmptyInput(): void
     {
         sleep(1);
-        $this->assertNull($this->geocoder->geocodePostcode(''));
+        $this->expectException(ApiErrorException::class);
+        $this->expectExceptionMessageMatches("/Nothing to search for.$/");
+        $this->geocoder->geocodePostcode('');
+    }
+
+    public function testGeocodePostcodeThrowsOnInvalidPostcode(): void
+    {
+        sleep(1);
+        $this->expectException(NoResultsFoundException::class);
+        $this->expectExceptionMessageMatches("/No results found.$/");
+        $this->geocoder->geocodePostcode('ZZZZZZZZZZZZ');
     }
 
     public function testGeocodePostcodeReturnsGeoCoordinates(): GeoCoordinates