Reference

Errors

Every failure uses the same envelope, so one error handler covers the whole API.

{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "The request parameters are invalid.",
    "details": {
      "q": ["Provide a search term in the \"q\" parameter."]
    }
  },
  "request_id": "3f7a2c18-9d41-4c7e-b0a2-6e5f1d8b4c93"
}

Error codes

Status	Code	Meaning	What to do
401	unauthenticated	Missing or unrecognised API key.	Check the header name and the key value.
403	forbidden	Key revoked, expired, IP-blocked, or account suspended.	Regenerate the key or check its IP allowlist.
404	not_found	No such record, or no such endpoint.	Treat as "no result" — usually not a bug.
422	validation_failed	Parameters failed validation.	Read `details` — it is keyed by field name.
429	rate_limit_exceeded	A quota window is exhausted.	Wait `Retry-After` seconds, then retry.
500	server_error	Something failed on our side.	Retry with backoff; report the `request_id` if it persists.

Request IDs

Every response — success or failure — carries an X-Request-Id header, and error bodies repeat it as request_id. Log it. It identifies one exact request in your dashboard's API log and is the fastest way for us to investigate a report.

A robust client

$response = Http::withHeaders(['X-API-Key' => $key])
    ->retry(3, fn ($attempt, $exception) => $attempt * 1000)
    ->get($url);

if ($response->status() === 429) {
    // Honour the server's own advice rather than guessing.
    sleep((int) $response->header('Retry-After'));
}

if ($response->failed()) {
    Log::warning('Address API error', [
        'request_id' => $response->header('X-Request-Id'),
        'code' => $response->json('error.code'),
        'message' => $response->json('error.message'),
    ]);
}

422 or 404?

They mean different things and deserve different handling. 422 says the input was malformed — a five-digit PIN code, for example — and retrying unchanged will fail identically. 404 says the input was well-formed but nothing matched, which is often a perfectly normal answer to show a user.

Previous Rate Limits Next Examples