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
| Code | HTTP | Name | Meaning |
|---|---|---|---|
| 20001 | 400 | VALIDATION_ERROR | A field is missing or invalid; see details |
| 20002 | 400 | INVALID_EXTERNAL_ID | ExternalUserId is missing, too long, or looks like an email or phone |
| 20003 | 400 | PII_NOT_ALLOWED | Personal data sent to a pseudonymous Service |
| 20004 | 400 | MAPPING_FAILED | The ingest payload doesn’t contain the mapped fields |
| 20006 | 400 | QR_INVALID | The scanned QR isn’t an EFIQ Rewards QR, or can’t be read |
| 20101 | 401 | INVALID_CREDENTIALS | Wrong or missing credentials |
| 20102 | 401 | CREDENTIAL_EXPIRED | The API key has expired |
| 20103 | 401 | CREDENTIAL_REVOKED | The API key was revoked |
| 20104 | 401 | INVALID_SIGNATURE | A signed request’s signature didn’t match |
| 20201 | 402 | SUBSCRIPTION_REQUIRED | No plan with the API (Business or Enterprise) |
| 20202 | 402 | SUBSCRIPTION_EXPIRED | Plan lapsed; read-only during the grace period |
| 20203 | 402 | API_ACCESS_NOT_IN_PLAN | Plan doesn’t include the API; move to Business or Enterprise |
| 20204 | 402 | LINK_CREDITS_EXHAUSTED | Not enough links left, from your plan and bought together; buy links to make more |
| 20301 | 403 | INSUFFICIENT_SCOPE | The restricted key lacks the scope |
| 20302 | 403 | IP_NOT_ALLOWED | Caller IP is not in the Service allowlist |
| 20303 | 403 | CAMPAIGN_NOT_PERMITTED | The Service can’t use that campaign |
| 20304 | 403 | ACCOUNT_DISABLED | The account is disabled |
| 20305 | 403 | FORBIDDEN | Not allowed for this credential |
| 20306 | 403 | WRONG_BUSINESS | The reward belongs to a different business |
| 20307 | 403 | ACCOUNT_SUSPENDED | The organization is suspended, so API access is paused |
| 20308 | 403 | SCANNER_DISABLED | The Scanner app isn’t turned on for this business |
| 20309 | 403 | PLAN_LIMIT_REACHED | A plan limit: Services, API keys, links in one set, reward types, or what you can spend on links this period |
| 20310 | 403 | PASSWORD_CHANGE_REQUIRED | A Scanner staff login has to choose its own password first |
| 20311 | 403 | EMAIL_NOT_VERIFIED | The account owner has to confirm their email before creating campaigns or importing contacts |
| 20404 | 404 | NOT_FOUND | No such resource in your account |
| 20405 | 405 | METHOD_NOT_ALLOWED | HTTP method not supported on this path |
| 20410 | 410 | LINK_REVOKED | The link was revoked |
| 20411 | 410 | LINK_EXPIRED | The voucher expired |
| 20901 | 409 | IDEMPOTENCY_CONFLICT | Same Idempotency-Key with a different body |
| 20902 | 409 | CAMPAIGN_NOT_ACTIVE | The campaign is not active or has ended |
| 20903 | 409 | INVENTORY_EXHAUSTED | The campaign’s rewards have run out |
| 20904 | 409 | CONFLICT | The request conflicts with the current state |
| 20905 | 409 | ALREADY_REDEEMED | The voucher was already redeemed |
| 20907 | 409 | SET_FULL | The set has no links left to hand out; extend it |
| 20908 | 409 | SET_NOT_ACTIVE | The set was cancelled or has expired |
| 21301 | 413 | BATCH_TOO_LARGE | More than 10,000 items in one request (split into several batches) |
| 22901 | 429 | RATE_LIMITED | Too many requests; retry after the Retry-After header |
| 25001 | 500 | INTERNAL_ERROR | Something went wrong on our side; safe to retry with the same Idempotency-Key |
| 25003 | 503 | SERVICE_UNAVAILABLE | Temporarily unavailable; retry with backoff |
| 25004 | 503 | MAINTENANCE | Scheduled 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.