Errors

Errors use application/problem+json. Branch on the stable code field rather than matching the human-readable message. The type link opens the description of that code.

{
  "type": "https://semantil.com/api/reference/errors#invalid_api_key",
  "title": "Invalid API key",
  "status": 401,
  "code": "invalid_api_key",
  "detail": "Provide a valid API key using the Authorization: Bearer header."
}

Practical handling

Status	What to do
400	Fix the request; retrying unchanged will not help. detail names the parameter.
401	Check or replace the API key.
402	insufficient_credits: nothing was charged. Request fewer rows, wait for usage.resets_at, or upgrade.
403	upgrade_required: the plan does not include it, follow upgrade_url. api_key_restricted: create a key with the default access. access_scope_restricted: the operation is outside your invitation or evaluation access; contact Semantil.
429	Respect Retry-After (also retry_after in the body), then retry with backoff.
5xx	Retry idempotent requests with exponential backoff and jitter.

Credits on every response

Every successful search, breakdown, lookalike and domain response carries _meta.usage, including responses with no results: credits charged by the call, remaining, the limit, and resets_at (the renewal date; null for evaluation access that does not renew). The same values are in the X-Credits-* headers.

Search and lookalike also return limit: the row count requested, the count applied, and limited_by (max_per_request, plan or credits) when fewer rows were returned than asked for. Search returns has_more when another page of exact results exists.

The live GET /api/errors endpoint lists the current problem codes without requiring an API key.