Errors

Every Rate Capture API error has an HTTP status and a short code that says exactly what went wrong. They're grouped here by what you should do next.

In short

When a call fails, the API answers with a short error code that says what to do next. This page groups the codes by action: fix the request, check the key, or wait and try again. Developers should make their code act on the code. Everyone else can look a code up here.

The first part covers codes about the request, the key and timing. Codes about credits, runs and rates are in their own section at the end.

What an error looks like

The Rate Capture API always answers an error in this shape. details appears only when there is more to say, such as which fields were wrong. 

{
  "error": {
    "code": "validation_failed",
    "message": "The report was not created; see details.",
    "details": {
      "nights": ["Choose a stay length of 1 to 7 nights."],
      "properties": ["Add at least one property."]
    }
  }
}
Check the code, not the message

Messages are written for people and may be reworded, so make your code decide what to do from error.code.

The Lighthouse-compatible API sends message and an errors list, as Lighthouse does. Each entry in the list has status, code, title and detail, and code is one of the codes listed here. Tools that only read message keep working. 

{
  "message": "subscriptionId is required",
  "errors": [
    {"status": 400, "code": "invalid_filter", "title": "Bad request", "detail": "subscriptionId is required"}
  ]
}

Fix the request

Something in the request is wrong. Sending it again unchanged will fail again.

Status Code What it means
422 validation_failed A field in the body is wrong. details lists each field with what to fix.
422 invalid_json The body isn't valid JSON, or isn't a JSON object.
422 invalid_limit limit is not a whole number in range. See lists and pages.
422 invalid_cursor cursor didn't come from this list. Pass back the nextCursor you were given, unchanged.
422 invalid_status status isn't queued, running or completed.
422 invalid_date from or to isn't a YYYY-MM-DD date.
422 invalid_reference More than 100 references in one reference filter.
422 invalid_idempotency_key The Idempotency-Key is longer than 200 characters.
422 idempotency_mismatch This Idempotency-Key was already used for a different request. Use a new key for each new action.
404 not_found No such path (under /lighthouse/v3, an endpoint Beacon doesn't provide answers 501 not_supported instead). Check the address against the base URLs. For a report or run that can't be found, see Rate Capture codes.
404 endpoint_not_found The Lighthouse-compatible API's answer for an address that isn't under /lighthouse/v3, such as /lighthouse/v2/rates, or for /lighthouse/v3 with no endpoint. It is Lighthouse's code for an unknown path.
405 method_not_allowed The path doesn't take that method. The Allow header lists the ones it does.

Check the key

The key is missing, wrong or not allowed to do this. See API keys for the order these are checked in.

Status Code What it means
401 missing_token No key was sent.
401 invalid_token The key isn't one Beacon issued.
401 key_revoked The key was revoked. Create a new one.
401 key_expired The key is past its expiry date. Create a new one.
401 user_disabled The person who created the key, or your company, is no longer active.
403 ip_not_allowed The request came from an address the key doesn't allow.
403 scope_read_only A write request with a read key.

Wait, then try again

Nothing is wrong with the request. Wait, then send it again. When the answer has a Retry-After header, wait at least that many seconds. After a 429, a 500, an idempotency_in_progress or a dropped connection, send the same Idempotency-Key, so a write isn't done twice.

Status Code What it means
429 rate_limited Over the key's per-minute limit, or too many unknown keys from your address. Wait for the seconds in Retry-After. If it was for unknown keys, the wait is an hour: check the key you are sending. See request limits.
409 idempotency_in_progress The first request with this Idempotency-Key is still being handled. Wait the 5 seconds in Retry-After, then send it again with the same key.
500 internal_error Something went wrong on Beacon's side, and it has been logged. Safe to retry.

How to send a write again safely is in sending a write again.

Rate Capture codes

Only the Rate Capture API and its Lighthouse-compatible API send these.

Add credits

Status Code What it means
402 insufficient_credits Not enough credits to start the run. details gives your balance and how many are required. Nothing was charged. If you used POST /v1/runs, no report was kept either; a report you created first stays. Buy credits in the Beacon Pro app, then start it again with a new Idempotency-Key, because Beacon stores this answer against the old one. Never sent to a company with unlimited credits.

Wait for a run, then try again

Status Code What it means
409 run_not_completed The run is still going, and this call needs a finished run. Check the run again later. If you sent an Idempotency-Key, you can send the same one when you try again: Beacon doesn't keep this answer against it.
409 retry_cooldown Failed checks of this run were retried less than 10 minutes ago, in the app or with this call. details.retryAfterSeconds says how long to wait. If you sent an Idempotency-Key, you can send the same one when you try again: Beacon doesn't keep this answer against it.
429 too_many_active_runs Your company already has as many runs queued or running at once as it may: 5, unless Beacon has raised your company's limit. Start this one when one of them finishes. There's no Retry-After header. Nothing was charged. See company limits.

Not there, or not any more

Status Code What it means
404 not_found No such report or run, or one this key can't see. Check the key's visibility.
409 report_already_run The report already has its run. To capture the list again, start a new run with POST /v1/runs.
410 results_purged The run's rows were deleted, by you or by your company's retention period. The run itself still answers. POST /v1/runs/{id}/retry answers this as a 409 instead, which isn't kept against an Idempotency-Key.
501 not_supported A Lighthouse endpoint that Beacon doesn't provide. The message lists the three that it does.

Fix a rates request

These come from the rates endpoints and the Lighthouse-compatible API. The Lighthouse-compatible API gives the code inside its errors list, as above.

Status Code What it means
400 invalid_filter A rates filter is out of range, the Lighthouse subscriptionId is missing, or the Lighthouse currency is not the subscription's currency. The message names the filter.
400 invalid_format The Lighthouse format isn't json or csv.
400 invalid_page, invalid_per_page The Lighthouse page or per_page is out of range, or page is past the last page.