Errors

This page lists the HostRepute API error codes, with the exact JSON body of each and what to do about it.

Every error is JSON with Content-Type: application/json, whether or not the request sent an Accept header. Each body has a message; validation errors add errors, and the credit error adds the credit counts. Base your code on the status code and those extra fields. Treat message as text for people: some messages name internal models, and one is empty.

Status	Means	Retry?
401	The token is missing, wrong, revoked or expired.	No. Fix the token.
402	The team doesn’t have enough credits for a check.	After someone buys credits.
403	The token lacks the ability, or the plan lacks the feature.	No. Use a token with the ability, or change the plan.
404	The path, or the item it names, doesn’t exist in your team.	No.
405	The path exists, but not with this HTTP method.	No. Use the method in the message.
422	A parameter or field is invalid, or a limit is reached.	Only after you fix the request.
429	Too many requests in the last minute.	Yes, after Retry-After seconds.
500	Something failed on HostRepute’s side.	Yes, later and with a growing wait. Read the note below.

Unauthenticated (401)

The Authorization header is missing, the token is mistyped, or the token was revoked or has expired. Read authentication and API tokens.

Response (401)

{ "message": "Unauthenticated." }

Not enough credits (402)

Only the three check endpoints answer 402: POST /api/v1/blacklist/check, POST /api/v1/certificates/check and POST /api/v1/deliverability/check. Nothing is charged and nothing starts. required_credits is the cost of the check and available_credits the team’s balance.

Response (402)

{ "message": "Insufficient credits.", "required_credits": 1, "available_credits": 0 }

The team’s Owner can buy credits: read credits. Read run checks and wait for results for how checks use them.

Not authorized (403)

The token is valid but doesn’t hold the ability the operation needs. GET /api/v1/metrics also answers 403 when the team’s plan doesn’t include Prometheus metrics. The body doesn’t say which of these it is.

Response (403)

{
  "message": "This action is unauthorized."
}

Not found (404)

The answer depends on what wasn’t found:

• No item with this UUID. The message names the internal model and the value you sent:

  Response (404)

  {
    "message": "No query results for model [App\\Models\\Host] 01a178db-0000-7000-8000-000000000000"
  }

• The item belongs to another team. The message is empty:

  Response (404)

  {
    "message": ""
  }

  An email authentication check older than your plan keeps its history answers the same way.

• No such path.

  Response (404)

  {
    "message": "The route api/v1/nope could not be found."
  }

• An email authentication check with a check profile that isn’t in your team answers {"message": "Monitoring profile not found."} and uses no credit.

Method not allowed (405)

The path exists, but not with the HTTP method you used. The message lists the methods it supports:

Response (405)

{
  "message": "The PATCH method is not supported for route api/v1/blacklist/check. Supported methods: POST."
}

Invalid request (422)

A query parameter or body field is missing or invalid, or the request would go past a limit. errors maps each field to its messages, and message repeats the first one, followed by (and 1 more error) or (and N more errors) when there are others.

Response (422)

{
  "message": "The host (domain or IP address) is required. (and 1 more error)",
  "errors": {
    "host": ["The host (domain or IP address) is required."],
    "callback_url": ["The callback URL must be a valid HTTPS URL."]
  }
}

A request body that isn’t valid JSON is read as empty, so it fails with the “required” errors of its fields.

Common 422 messages:

Field	Message	Cause
host	Your current plan cannot monitor more hosts.	POST /api/v1/hosts when the team monitors as many domains and IPs as its plan allows.
host	The host must be a valid public IP address or domain name.	A private, loopback or reserved address in POST /api/v1/hosts.
callback_url	The callback url must be a public HTTPS webhook URL.	The callback_url doesn’t resolve to a public address. Read receive webhooks.
data_source_group_uuid	No monitoring profile is available for this team.	A blocklist check without a profile, in a team that has no check profile.
data_source_group_uuid	The selected monitoring profile has no active data sources.	The check profile has no blocklists.
per_page	The per page field must not be greater than 100.	A list request with per_page over 100. Read pagination.

The messages keep the API’s internal words: a host is a domain or IP, a monitoring profile a check profile, and a data source a blocklist.

Too many requests (429)

The team, or the agent or person behind the request, has used up a rate limit. Wait the number of seconds in Retry-After before the next request. Read rate limits.

Response headers (429)

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Retry-After: 59
X-RateLimit-Reset: 1793047746

Response (429)

{
  "message": "Too Many Attempts."
}

Server error (500)

Something failed on HostRepute’s side. The body doesn’t say what:

Response (500)

{
  "message": "Server Error"
}

Retry a read later, waiting longer each time. Before you resend a request that changes something, check whether the first one went through: after a failed POST /api/v1/hosts, for example, list your domains and IPs. The API has no list of the checks you started, so don’t resend a check automatically. An email authentication check that fails with 500 is refunded. If 500 answers keep coming, email [email protected] with the time and the request path.

Related

• Authentication and API tokens explains 401 and 403.
• Rate limits explains 429 and its headers.
• Run checks and wait for results explains 402 and refunds.
• Pagination lists the paging parameters and their limits.