Errors & retries

The SDK throws typed errors. Catch the parent class to handle anything, or catch a specific subclass for fine-grained logic.

import Hawkings, {
  HawkingsError,
  AuthenticationError,
  RateLimitError,
  InvalidRequestError,
  APIError,
} from "@hawkings/sdk";

try {
  await hk.courses.create({ name: "" });
} catch (err) {
  if (err instanceof InvalidRequestError) {
    console.error(err.fields); // { name: "is required" }
  }
}

use Hawkings\Exception\ApiError;
use Hawkings\Exception\AuthenticationError;
use Hawkings\Exception\RateLimitError;
use Hawkings\Exception\InvalidRequestError;

try {
    $hk->courses->create(['name' => '']);
} catch (InvalidRequestError $e) {
    error_log(print_r($e->fields, true)); // ['name' => 'is required']
} catch (ApiError $e) {
    // catch-all for any Hawkings SDK error
}

In PHP the exception hierarchy is rooted at \Hawkings\Exception\ApiError, with subclasses for each error type (AuthenticationError, PermissionError, NotFoundError, InvalidRequestError, RateLimitError, IdempotencyError, NetworkError). Catch ApiError to handle anything.

Error taxonomy

Class	HTTP	When it fires	Retryable?
`AuthenticationError`	401	Bad/expired API key, missing scope.	No
`PermissionError`	403	Key valid, but no access to this resource.	No
`NotFoundError`	404	Resource doesn’t exist or is in another workspace.	No
`InvalidRequestError`	422	Validation failed. Inspect `err.fields`.	No
`RateLimitError`	429	Too many requests. `err.retry_after` is the seconds to wait.	Yes (auto)
`IdempotencyError`	409	Same `idempotency_key` reused with a different payload.	No
`APIError`	5xx	Hawkings is having a moment. Auto-retried with backoff.	Yes (auto)
`NetworkError`	n/a	DNS, TLS, timeout. Auto-retried with backoff.	Yes (auto)

Automatic retries

The SDK retries 429 and 5xx responses automatically with exponential backoff and jitter. Defaults:

new Hawkings({
  max_retries: 3,         // default
  retry_delay_ms: 500,     // base; doubles each attempt
  retry_on: ["429", "5xx", "network"],
});

new \Hawkings\Client([
    'max_retries' => 3,         // default
    'retry_delay_ms' => 500,    // base; doubles each attempt
    'retry_on' => ['429', '5xx', 'network'],
]);

Disable for a specific call:

await hk.courses.create({ name: "..." }, { max_retries: 0 });

$hk->courses->create(['name' => '...'], ['max_retries' => 0]);

Idempotency keys

Any create*, update*, or AI generation call can carry an Idempotency-Key. Same key + same body = same response, even if you call it 100 times. Different body with the same key throws IdempotencyError.

await hk.submissions.create(
  { assignmentId, studentId, content },
  { idempotency_key: "subm-2026-05-10-abc" },
);

$hk->submissions->create(
    ['assignment_id' => $assignmentId, 'student_id' => $studentId, 'content' => $content],
    ['idempotency_key' => 'subm-2026-05-10-abc'],
);

Idempotency records live for 24 hours.

Error envelope

Every error response carries a structured body:

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_field",
    "message": "name is required.",
    "fields": { "name": "is required" },
    "request_id": "req_01HX9..."
  }
}

When opening a support ticket, attach request_id — it’s all we need to trace a request end-to-end.

Get started

Core concepts

Guides

Error taxonomy

Automatic retries

Idempotency keys

Error envelope

​Error taxonomy

​Automatic retries

​Idempotency keys

​Error envelope

Error taxonomy

Automatic retries

Idempotency keys

Error envelope