API Errors

The Kigo API returns errors in one of two JSON formats. The format an endpoint uses is shown in the error responses on its reference page.

Problem Details

Newer endpoints return 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.
Ignore unknown members. Some problem types include extra fields (for example, 412 responses carry the current updated_at).

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

Error Payload

Other endpoints, including the authentication endpoints, return an application/json body with an error_code and an error_message:

{
  "error_code": "authorization_error",
  "error_message": "Unauthorized access or invalid refresh token."
}

Match on error_code; error_message is human-readable and may change. Possible error_code values:

`error_code`	Meaning
`access_code_fully_redeemed`	A reusable access code has reached its maximum number of redemptions.
`active_otp_pending`	A one-time passcode was already sent and is still active.
`already_used`	The resource has already been used.
`asset_unavailable`	The requested asset is not available.
`authorization_error`	The token is missing, expired, or invalid, or the caller is not permitted to perform the action.
`bad_request_error`	The request is malformed.
`database_error`	A database error occurred.
`domain_dependency_error`	A dependent Kigo service failed.
`expired_input`	The supplied value has expired.
`fail_to_fulfill_gift_card`	The gift card could not be fulfilled.
`first_and_last_name_required`	First and last name are required.
`internal_error`	An unexpected server error occurred.
`invalid_input`	The request failed validation, or an identifier or credential is invalid.
`invalid_recaptcha`	The reCAPTCHA check failed.
`invalid_sign_in_method`	The account does not use this sign-in method.
`missing_location_id`	A location ID is required.
`missing_merchant_id`	A merchant ID is required.
`non_sufficient_funds`	The balance is not sufficient for the request.
`not_found`	The requested resource does not exist.
`not_implemented`	The operation is not supported.
`offer_unavailable`	The offer exists but cannot be redeemed right now.
`place_id_not_found`	The place ID could not be found.
`service_error`	An external service failed.
`too_many_requests`	The rate limit has been exceeded.
`unique_violation`	The resource already exists.
`validation_error`	The request failed validation.

Problem Types

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.

Password reset already sent

HTTP 403. The account needs a password reset and a reset email was already sent recently, so no new email was sent. Shares 403 with Unauthorized; use type to tell them apart.

Access code claimed

HTTP 409 / 403. The access code has already been claimed. Read status for the exact code.

Access code disabled

HTTP 403. The access code is disabled.

Access code expired

HTTP 410 / 403. The access code has expired. Read status for the exact code.

Access code fully redeemed

HTTP 403. A reusable access code has reached its maximum number of redemptions.

Access code type unsupported

HTTP 403. The access code is reusable, and this endpoint does not accept reusable codes.

Access code invalid for program

HTTP 403. The access code belongs to a different program.

Access code required

HTTP 400. The program requires an access code and none was supplied.

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 409 (also 422). The offer is not available for redemption. Read status for the exact code.

Redemption method not supported

HTTP 400. The offer does not support the requested redemption method.

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.

Requests

Request body too large

HTTP 413. The request body exceeds the size limit for the endpoint, or the idempotency buffering limit.

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.

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.