Back to QR Code toolAPI

QR Code API

Generate SVG or PNG data URL QR codes from links or text. Quota is counted by request.

Authentication
Create an API key from settings. The full secret is shown once, so copy it into your agent or secret manager. Later views only show a masked key.
Authorization: Bearer ecw_live_...
X-API-Key: ecw_live_...
Quota And Rate Limits
API usage is tracked separately. Successful and limit responses expose quota.remaining and rateLimit.remaining (plus the matching X-* headers). Minute limits use a UTC minute window and are counted per API key and tool; requests beyond the limit return 429 rate_limited, so wait for Retry-After before retrying.
X-Quota-Limit: 1000
X-Quota-Remaining: 997
X-RateLimit-Limit: 30
Safe Retries
When a request times out or your agent retries automatically, reuse the same Idempotency-Key. The same key and body reuse the result; a different body returns idempotency_conflict, while an active request returns idempotency_in_progress.
Idempotency-Key: order-sync-2026-06-14-001
Grant the smallest scope
Choose only the tool scope each API key needs, such as tools:gtin:generate. A scope limits tools; it does not increase the owner membership tier, quota, or rate limit.
Scope: tools:gtin:generate
Keep the API key secret
The full API key is shown only once. Store it in an environment variable or secret manager; never put it in code, URLs, logs, screenshots, or chat. Delete and recreate it if you suspect exposure.
ECOMWITH_API_KEY=ecw_live_...

Errors And Recovery

Error responses use error.code and error.message. Handle the status and code first, then decide whether to wait or retry the same business request with its original Idempotency-Key.

400invalid_request

Fix the JSON body before sending again; do not repeat an unchanged request.

401authentication_required / invalid_api_key

Check Authorization: Bearer or X-API-Key; never put the full key in error logs.

403membership_required / insufficient_scope

Check the current plan and the key scope; a scope cannot increase membership quota.

409idempotency_conflict / idempotency_in_progress

Keep one key for the same business request; stop on conflict, or wait and retry an active request with the same key.

413payload_too_large

Reduce the request body to the current plan payload limit before sending again.

429quota_exceeded / rate_limited / concurrency_limited

Read X-Quota-*, X-RateLimit-*, and Retry-After; stop at zero quota and wait for rate or concurrency limits.

Error response shape

{"object":"tool_api.error","error":{"code":"invalid_request","message":"Request body must be a JSON object."}}

Current Plan Limits

Limits are calculated from the current membership tier of the API key owner. Minute limits are counted separately for each API key and tool; requests beyond the limit return 429 rate_limited. Send requests sequentially and treat quota and rateLimit in each response as the source of truth.

Basic

Not included in API access today
Daily quota
Unavailable
Per request
Unavailable
Per minute
Unavailable
How to use it
If the API returns membership_required, stop and check the account plan.

Pro

Included
Daily quota
500 requests
Per request
1 QR code
Per minute
60 requests
How to use it
One request generates one QR code and does not use a quantity field. Stop requests when quota.remaining is 0.

Max

Included
Daily quota
5,000 requests
Per request
1 QR code
Per minute
200 requests
How to use it
One request generates one QR code and does not use a quantity field. Stop requests when quota.remaining is 0.

Send Requests Sequentially

For the same API key and tool, Ecomwith handles one request at a time. If the API returns 429 concurrency_limited, wait for the previous request to finish and retry with the same Idempotency-Key.

Copy This To Your Agent
Give this instruction to your automation agent so it knows how to authenticate, request, handle quota, rate limits, and safe retries.
You are my automation agent. Use the Ecomwith Tool API to call the QR Code API, and never print the full API key in logs, chat, or error messages.

Authentication:
- Read the secret from the ECOMWITH_API_KEY environment variable.
- Send Authorization: Bearer <ECOMWITH_API_KEY>.

Request:
- Endpoint: POST https://ecomwith.com/api/v1/tools/qrcode/generate
- Headers: Content-Type: application/json
- Body example: {"text":"https://example.com","format":"svg","size":300}
- One request generates one QR code and does not use a quantity field.

Current limits:
- Pro: 500 requests per day, 1 QR code per request, up to 60 requests per minute.
- Max: 5,000 requests per day, 1 QR code per request, up to 200 requests per minute.
- Basic does not include API access today. If the API returns membership_required, stop and ask me to check the plan.

Quota and rate-limit handling:
- Read quota.remaining and rateLimit.remaining from every response.
- If quota.remaining is 0, stop requests.
- Do not call the same tool concurrently. Wait for the previous request to finish before sending the next one.
- If the API returns 429 concurrency_limited, wait for the previous request to finish and retry with the same Idempotency-Key.
- If the API returns 429 rate_limited, wait before retrying. If it returns 429 quota_exceeded, stop and report that quota is exhausted.

Safe retries:
- Generate one stable Idempotency-Key for each business task, for example qr-product-page-123.
- On a network timeout or 5xx response, retry with the same Idempotency-Key. Do not switch to a new key.
- Do not automatically retry 400, 401, or 403 responses.
- If the API returns 409 idempotency_conflict, the same key was used with a different request body. Stop and ask me to confirm.

On success, return qrcode.dataUrl, format, quota.remaining, and rateLimit.remaining.

Example Requests

curl -X POST https://ecomwith.com/api/v1/tools/qrcode/generate \
  -H "Authorization: Bearer $ECOMWITH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: qr-001" \
  -d '{"text": "https://example.com", "format": "svg", "size": 300}'