API support: getting started and errors

This page gathers what you need to use the Domain Feed API without writing to us: how to get and use your key, what limits your plan has, what each error means and what to do if you lose the key. Every endpoint, with its parameters and examples, is in the domain feed reference.

Getting started

Subscribe. Pick a plan on the feed page. The monthly Pro plan includes a 7-day free trial.
Open the link in your email. When you pay, or start the trial, you get an email with a one-time link at the address you bought with. It has a limited lifetime (today, 72 hours).
Claim your key. On the link’s page, press the button to see your key. It is shown only once: copy it into a secrets manager or an environment variable. Cifradia stores only a fingerprint of the key and cannot show it to you again.
Make your first request.

export KEY="<your key>"
curl -H "Authorization: Bearer $KEY" "https://api.cifradia.com/v1/tlds"

If you get a JSON with "status": true, you are in. If not, check the errors.

Authentication

Every request carries the Authorization: Bearer <your key> header. Keys start with cfd_live_.
Never put the key in the URL. URLs end up in browser history, proxy logs and Referer headers. The API accepts the key only in the header.
There is one key per subscription. It is personal and non-transferable; treat it like a password, and do not commit it to repositories or use it in code that runs in a browser.
If you had already used a free trial before, your new key can be claimed but answers 401 until your first payment (section 10 of the API terms).

Plans and limits

The plans table shows each plan’s requests per minute and per day, days of history, included TLDs and whether the daily ZIP is included.

Per minute: if you go over, the API answers 429 and the Retry-After header says how many seconds to wait.
Per day: the quota resets at 00:00 UTC. When it is used up, the API answers 429 and Retry-After gives the seconds until then.
What counts: requests with a valid key that pass the per-minute limit, including those that end in 400 or 403. Those that end in 401 or 429 do not use quota.
Headers: responses to requests with a valid key carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset if your key has a per-minute limit, and X-Daily-Quota-Limit and X-Daily-Quota-Remaining if it has a daily quota, so you know what is left.
Outside your plan: asking for a TLD your plan does not include, a date before your history or the daily ZIP without having it gives 403. Going over a limit does not generate extra charges.

To avoid hitting the limit, space out your requests and retry only after Retry-After, not in a loop.

Errors

Errors carry an HTTP status code and a JSON with a description. These are the ones the API returns:

Code	When it happens	What to do
`400`	A value is not valid: a date that is not `yyyymmdd`, a value outside the allowed ones for `dm`, `dcm`, `idn`, `sorton` or `source`, a keyword shorter than 4 characters on `/v1/keywords`, or a domain without a TLD on `/v1/history`.	Fix the request. The `error` field says what failed.
`401`	The key is missing, wrong, revoked (for example, after cancelling) or suspended.	Check the `Authorization: Bearer` header and that you copied the whole key. If everything looks right, write to us.
`403`	Your plan does not include what you ask for: a TLD, a date before your history or the daily ZIP.	Ask only for what your plan includes or change plan.
`404`	Without `date`, there is no data yet for what you ask. On the claim link, the link is not valid, has expired or was already used.	Retry later, or write to us if it is a claim link.
`422`	A parameter has the wrong type or range: an integer that is not one, a `limit` above the maximum, a negative `offset`, or `domain` missing on `/v1/history`.	Fix the request. `detail` lists the parameters with a problem.
`429`	You went over the per-minute limit or the daily quota.	Wait the seconds in `Retry-After` and retry.
`503`	The query is too heavy or the service is busy. It carries `Retry-After`. `/health` also answers `503` when the service is degraded.	Narrow the date range or the filters, or retry after `Retry-After`.

The 400, 401, 403, 404 and 429 error responses have this shape:

{ "detail": { "status": false, "error": "rate limit exceeded" } }

A 422 carries in detail a list with the parameter (loc), the reason (msg) and the type (type). A 503 for a heavy query carries { "status": false, "error": "…" } without detail. An internal error (500) is a failure on our side, not in your request: retry and, if it persists, write to us.

When the data is ready

The data is updated once a day. The sync starts at 07:00 UTC and currently takes about 25 minutes, so the previous day’s changes are usually available around 07:30 UTC. This is a typical timing, not a guarantee. If you query earlier, the previous day’s changes may not be there yet; without date, the API returns the latest day with data. The scope of the service is in the API terms.

Billing and cancellation

Payment is processed by Paddle, our reseller, which issues the invoice and handles taxes.
You can cancel at any time from the Paddle customer portal or from the link in its emails. Access continues until the end of the paid period and then the key is revoked. Details in the Cancellation section.
To ask for a refund, see the Refunds section: it includes the 5-business-day withdrawal right after your first payment and the refund for a service failure.
To change plan or billing cycle, write to us from the subscription’s email (plan changes). The key is kept and takes the new plan’s limits.

Lost or compromised key

Cifradia cannot recover a key, but it can give you a new one. Write to contacto@cifradia.com from your subscription’s email and we will send you a new link to claim it. The previous key stops working, so update your integrations when you receive it (access keys).

If you suspect someone else knows your key, tell us as soon as possible so we can replace it.

Contact

Write to contacto@cifradia.com or use the contact page. We are available Monday to Friday, 8:00 to 18:00 (Bogotá time). To help us help you quickly, include the subscription’s email, the endpoint and parameters you used, the error code and the approximate time (UTC). Never send us your full key.