Errors

Errors use standard HTTP status codes and a stable numeric code you can branch on.

Error body
{
  "code": 20204,
  "message": "No links left. Buy links to make more.",
  "status": 402,
  "more_info": "https://docs.efiqone.com/errors/20204",
  "request_id": "RQ0102674df9d44149ab5694205460d92a"
}

Codes

CodeHTTPNameMeaning
20001400VALIDATION_ERRORA field is missing or invalid; see details
20002400INVALID_EXTERNAL_IDExternalUserId is missing, too long, or looks like an email or phone
20003400PII_NOT_ALLOWEDPersonal data sent to a pseudonymous Service
20004400MAPPING_FAILEDThe ingest payload doesn’t contain the mapped fields
20006400QR_INVALIDThe scanned QR isn’t an EFIQ Rewards QR, or can’t be read
20101401INVALID_CREDENTIALSWrong or missing credentials
20102401CREDENTIAL_EXPIREDThe API key has expired
20103401CREDENTIAL_REVOKEDThe API key was revoked
20104401INVALID_SIGNATUREA signed request’s signature didn’t match
20201402SUBSCRIPTION_REQUIREDNo plan with the API (Business or Enterprise)
20202402SUBSCRIPTION_EXPIREDPlan lapsed; read-only during the grace period
20203402API_ACCESS_NOT_IN_PLANPlan doesn’t include the API; move to Business or Enterprise
20204402LINK_CREDITS_EXHAUSTEDNot enough links left, from your plan and bought together; buy links to make more
20301403INSUFFICIENT_SCOPEThe restricted key lacks the scope
20302403IP_NOT_ALLOWEDCaller IP is not in the Service allowlist
20303403CAMPAIGN_NOT_PERMITTEDThe Service can’t use that campaign
20304403ACCOUNT_DISABLEDThe account is disabled
20305403FORBIDDENNot allowed for this credential
20306403WRONG_BUSINESSThe reward belongs to a different business
20307403ACCOUNT_SUSPENDEDThe organization is suspended, so API access is paused
20308403SCANNER_DISABLEDThe Scanner app isn’t turned on for this business
20309403PLAN_LIMIT_REACHEDA plan limit: Services, API keys, links in one set, reward types, or what you can spend on links this period
20310403PASSWORD_CHANGE_REQUIREDA Scanner staff login has to choose its own password first
20311403EMAIL_NOT_VERIFIEDThe account owner has to confirm their email before creating campaigns or importing contacts
20404404NOT_FOUNDNo such resource in your account
20405405METHOD_NOT_ALLOWEDHTTP method not supported on this path
20410410LINK_REVOKEDThe link was revoked
20411410LINK_EXPIREDThe voucher expired
20901409IDEMPOTENCY_CONFLICTSame Idempotency-Key with a different body
20902409CAMPAIGN_NOT_ACTIVEThe campaign is not active or has ended
20903409INVENTORY_EXHAUSTEDThe campaign’s rewards have run out
20904409CONFLICTThe request conflicts with the current state
20905409ALREADY_REDEEMEDThe voucher was already redeemed
20907409SET_FULLThe set has no links left to hand out; extend it
20908409SET_NOT_ACTIVEThe set was cancelled or has expired
21301413BATCH_TOO_LARGEMore than 10,000 items in one request (split into several batches)
22901429RATE_LIMITEDToo many requests; retry after the Retry-After header
25001500INTERNAL_ERRORSomething went wrong on our side; safe to retry with the same Idempotency-Key
25003503SERVICE_UNAVAILABLETemporarily unavailable; retry with backoff
25004503MAINTENANCEScheduled maintenance; retry after the Retry-After header

Rate limits

Limits are per account per second: Starter 10, Pro 50, Business 100, Enterprise 300. Responses include X-RateLimit-Limit and X-RateLimit-Remaining.