Errors

Every error the API returns, and what to do about it.

Errors come back as JSON, with a stable error code to test in your code. Some carry extra fields that help you react:

{
  "error": "invalid_request",
  "fields": [
    { "path": "q", "message": "Too small: expected string to have >=1 characters" }
  ]
}

Match on error, not on the wording of a message: messages can change, codes do not.

A refused call never takes a search from your quota. The input, your plan and the removals are checked before anything is counted, and a search refused by a limit is not counted either. The one exception is a 404 from a single-module route: it is an answer (“nothing there”), and it counts. What takes a search →

Error codes

Your request

Status	Code	What happened	What to do
400	invalid_request	q is missing, empty or longer than 100 characters. fields lists each problem.	Send q with 1 to 100 characters.
400	invalid_query	q is not a Discord ID, a username or an invite link DisDog can recognise.	Check the input — see what you can search.
400	invalid_id	The {id} in the path is not a valid Discord ID.	Send the 17 to 20 digit ID.
400	invalid_name	The {name} is shorter than 2 or longer than 64 characters.	Send 2 to 64 characters.
400	invalid_invite	The {code} is not an invite code or invite link.	Send the code (disdog) or the link (discord.gg/disdog).
404	user_not_found	/v1/profile/{id}: no Discord account has this ID.	Check the ID. This counts as a search.
404	not_available	/v1/connections/{id}: the connections could not be read for this account right now.	Try again later. This counts as a search.
404	invite_not_found	/v1/invite/{code}: the invite does not exist or has expired.	Nothing. This counts as a search.
404	not_found	No such route.	Check the path and the method: every route is GET.
451	removed_by_owner	The owner of this Discord ID asked to be removed from DisDog.	Nothing: the ID is hidden from every search, for everyone. See Data removal.

Your key

Status	Code	What happened	What to do
401	invalid_api_key	No key sent, or a key that matches no account — mistyped, or replaced by a newer one.	Send your current key in Authorization: Bearer …, or get a new one.
403	plan_has_no_api	A Pup (free) key, on a route other than /v1/me and /v1/modules.	Upgrade to Hound or Alpha.
429	too_many_requests	More than 30 calls with a wrong key from your address in 15 minutes.	Fix the key, then wait up to 15 minutes.

Limits

Status	Code	Extra fields	What happened	What to do
429	rate_limited	retryAfterMs, resetAt, limit	Pup (website): less than 3 seconds since your last search.	Wait retryAfterMs milliseconds.
429	quota_exceeded	resetAt, limit	Today’s searches are used up.	Wait for resetAt (00:00 UTC), or upgrade.

Our side

Status	Code	What happened	What to do
500	internal_error	Something broke on our side.	Try again; if it persists, contact support.
502	source_unavailable, upstream_unavailable	A data source did not answer.	Retry with a backoff (2 s, 5 s, 15 s).
503	module_unavailable, upstream_busy	A source is down or overloaded.	Retry later.

In a search, a failing source never fails the whole call: that module answers "status": "error" and the others still come back.