Errors

The RevKeen API returns errors in a consistent envelope with a machine-readable code, a human-readable message, and — where applicable — the offending param and structured field-level details.

Reserve the message for display and the code for branching logic.

Error envelope

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "Customer email is required.",
    "param": "customer.email",
    "details": {
      "fields": {
        "customer.email": ["must be a valid email address"]
      }
    }
  }
}

HTTP status codes

Authentication and authorization errors

401 and 403 are separate categories. A 401 means RevKeen could not establish who is calling. A 403 means the caller is identified and the action is denied. Branch on error.type first, then on error.code.

401 — authentication_error

Every 401 carries an RFC 6750 challenge header:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="revkeen-api"
Content-Type: application/json

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Authentication required."
  }
}

403 — authorization_error

Retry guidance

Validation errors

Validation errors use type: invalid_request_error. Where RevKeen can identify the offending parameter, error.param names it — for example, a create that references a product that does not exist:

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "No such product: prod_123",
    "param": "product_id"
  }
}

A request that fails schema validation before it reaches the handler currently returns a different body — see Responses outside the envelope. Treat any 400 as a validation failure, and render the reason next to the offending input rather than surfacing the message alone.

Rate-limit errors

429 Too Many Requests always carries type: rate_limit_error, code: rate_limit_exceeded, a Retry-After header in whole seconds, and details.retry_after with the same value.

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after the period in Retry-After.",
    "details": { "retry_after": 12 }
  }
}

Retry-After, WWW-Authenticate and the X-RateLimit-* trio are all exposed through CORS on /v2, so a browser fetch client can read them.

Published plan limits are on the rate limits reference.

Reading the headers from an SDK

Every RevKeen SDK surfaces all four headers on the error it throws, so you do not have to reach for the raw response. A header the server did not send reads as null rather than zero, so a published X-RateLimit-Remaining: 0 is never confused with an unreported limit. The reset instant is parsed from UNIX seconds, and the retry delay is reported exactly as the server stated it — the SDK's own retry backoff is capped, this value is not.

import { RevKeenRateLimitError } from "@revkeen/sdk";

try {
  await revkeen.invoices.list();
} catch (error) {
  if (error instanceof RevKeenRateLimitError) {
    error.rateLimit.retryAfterSeconds; // number | null — Retry-After
    error.rateLimit.limit; // number | null — X-RateLimit-Limit
    error.rateLimit.remaining; // number | null — X-RateLimit-Remaining
    error.rateLimit.resetAt; // Date | null — X-RateLimit-Reset
  }
}

var requestError *revkeen.RequestError
if errors.As(err, &requestError) && requestError.Kind == revkeen.ErrorKindRateLimit {
    requestError.RateLimit.RetryAfter // *time.Duration
    requestError.RateLimit.Limit      // *int64
    requestError.RateLimit.Remaining  // *int64
    requestError.RateLimit.ResetAt    // *time.Time
}

try {
    $api->invoicesList();
} catch (\RevKeen\Runtime\RateLimitException $error) {
    $error->getRateLimit()->getRetryAfterSeconds(); // ?int
    $error->getRateLimit()->getLimit();             // ?int
    $error->getRateLimit()->getRemaining();         // ?int
    $error->getRateLimit()->getResetAt();           // ?DateTimeImmutable
}

Error code reference

Every error.code the API can return in the standard envelope, beyond the authentication and authorization codes above.

Where two statuses are listed, the one returned depends on the operation. Branch on error.code, not on the status alone.

Responses outside the envelope

These responses do not use the nested error object yet. Handle them by status code and the fields shown:

Examples

curl -i https://staging-api.revkeen.com/v2/payment-intents/pi_00000000 \
  -H "x-api-key: $REVKEEN_API_KEY"
# HTTP/1.1 404 Not Found
# { "error": { "type": "invalid_request_error", "code": "resource_missing", "message": "No such payment intent: 'pi_00000000'" } }

See also

Owner: david · Reviewed 6 Oct 2026 · Next review 6 Nov 2026