API Errors

The Kigo API returns errors as RFC 9457 Problem Details with the content type application/problem+json:

{
  "type": "https://docs.kigo.io/docs/api-errors#redemption-limit-reached",
  "title": "Redemption Limit Reached",
  "status": 409,
  "detail": "You have reached the limit of available redemptions for this offer."
}

How to detect a specific error

• Match on type. It is a stable, machine-readable identifier for the problem type. It is the correct field to branch on and will not change for wording or localization.
• Do not match on title or detail. These are human-readable and may change for localization or copy edits.
• Do not rely on the HTTP status code alone. Several problem types can share a status (for example, many conditions return 409). Use type to disambiguate.
• Read status for the exact HTTP status. A few type values are returned under more than one status (noted below); when that matters, use the response's status field.

Each problem type below is identified by the type value https://docs.kigo.io/docs/api-errors#<name>.

Authentication and authorization

Unauthenticated

HTTP 401. The request is not authenticated (missing or failed authentication).

Unauthorized

HTTP 401 / 403. The caller is not permitted to perform the action.

Invalid token

HTTP 401. The authentication token is invalid.

Forbidden

HTTP 403. The action is forbidden for this user.

Account locked

HTTP 423. The account is locked.

Access code claimed

HTTP 409. The access code has already been claimed.

Access code disabled

HTTP 403. The access code is disabled.

Access code expired

HTTP 410. The access code has expired.

Syndicator not found

HTTP 404. The requested syndicator does not exist.

Validation

Invalid input

HTTP 400 (also returned for some 403 / 409 / 422 cases). The request failed validation. Read status for the exact code.

Resources

Not found

HTTP 404. The requested resource does not exist.

Already exists

HTTP 409 (also 400 in one case). The resource already exists.

Conflict

HTTP 409 (also 410 for expired/gone cases). The request conflicts with the current state of the resource.

Invalid reference

HTTP 400. The request references an entity that does not exist (foreign-key violation).

Offers and lightning deals

Offer not found

HTTP 404. The requested offer does not exist.

Offer unavailable

HTTP 400. The offer is not available for redemption.

Redemption limit reached

HTTP 409. The user has no remaining redemptions for this offer.

Reservation limit reached

HTTP 409. The user has reached the reservation limit for this offer.

User already has active reservation

HTTP 409. The user already holds an active reservation for this offer.

Not a lightning deal

HTTP 400. The offer is not a lightning deal.

Lightning deal disabled

HTTP 409. The lightning deal is disabled.

Lightning deal expired

HTTP 409. The lightning deal has expired.

Lightning deal sold out

HTTP 409. The lightning deal is sold out.

Overlapping lightning deal

HTTP 409. A new lightning deal would overlap an existing one for the same offer.

SMS notifications disabled

HTTP 403. SMS notifications are disabled.

Rate limiting

Too many requests

HTTP 429. The rate limit has been exceeded.

Idempotency

Missing idempotency key

HTTP 400. The Idempotency-Key header is required for this request and was not provided.

Invalid idempotency key

HTTP 400. The Idempotency-Key header value is not a valid UUID.

Request body too large

HTTP 413. The request body exceeds the idempotency buffering limit.

Idempotency key reuse

HTTP 409. The Idempotency-Key was reused with a different request body.

Preconditions

Precondition failed

HTTP 412. A stale If-Match / optimistic-concurrency conflict. The response carries the current updated_at so the client can retry.

Server errors

Internal server error

HTTP 500 (also 501 for not-implemented). An unexpected server error occurred.

Database error

HTTP 500. A database error occurred.

Service error

HTTP 500 / 502 / 503. An external service dependency failed. Read status for the exact code.

Cache error

HTTP 500 / 503. A cache (Redis) error occurred.