Errors
Every error is an RFC 9457 problem with a stable code. The full list, and what to do with each.
The shape of an error
Errors use Content-Type: application/problem+json (RFC 9457):
HTTP/1.1 409 Conflict
Content-Type: application/problem+json
{
"type": "https://metricevo.com/problems/run_in_progress",
"title": "Conflict",
"status": 409,
"code": "run_in_progress",
"detail": "An audit for this site is already waiting or running.",
"requestId": "req_01JCA40000000000000000000",
"runId": "run_01JCA40000000000000000000"
}
| Field | Use it for |
|---|---|
code |
Branch on this. It is stable within v1. |
status |
The HTTP status, repeated. |
detail |
A sentence for people. It may change; do not parse it. |
requestId |
Quote it when you report a problem. |
siteId, runId |
On some conflicts: the existing object to use instead. |
Codes
| Status | code |
Means | What to do |
|---|---|---|---|
| 400 | invalid_request |
A field is missing or wrong, or the body is not a JSON object. | Fix the request from detail; do not retry unchanged. |
| 400 | url_policy_denied |
The address is not a public website. | See which addresses can be audited. |
| 400 | idempotency_key_required |
POST /audit-runs without an Idempotency-Key. |
Send one, for example a UUID. |
| 401 | unauthorized |
No key was sent. | Send Authorization: Bearer …. |
| 401 | invalid_api_key |
The key is wrong, revoked or expired, or its account is not active. | Check the key; create a new one if needed. |
| 403 | developer_mode_required |
Developer tools are off for the account (API-key calls, key management, automations, incoming webhooks). | The account owner turns them on in Settings → Developer tools. See Developer tools. |
| 403 | insufficient_scope |
The key lacks the scope this call needs. | Create a key with the scope named in detail. |
| 403 | session_required |
Key management with a key. | Manage keys in the app. |
| 404 | not_found |
No such id, or it belongs to another account, or no such endpoint. | Check the id and the path. |
| 405 | method_not_allowed |
The path exists, the method does not. | See the reference. |
| 409 | site_exists |
The site is already on your list. | Use siteId from the body. |
| 409 | run_in_progress |
The site already has a waiting or running audit. | Poll runId from the body. |
| 409 | idempotency_conflict |
The Idempotency-Key was used for another site. |
Use a new key for a new audit. |
| 403 | plan_limit |
Your plan does not include this, for example a write with an API key or extra sites on Free. | Upgrade, or choose what the plan includes. |
| 403 | session_required |
Billing changes need a signed-in session, not an API key. | Do it in the app under Plan & billing. |
| 409 | already_subscribed |
A checkout for an account that already has a plan. | Change the plan in the billing portal. |
| 409 | no_billing_account |
The billing portal before any checkout. | Choose a plan first. |
| 429 | quota_exceeded |
An account limit: sites, audits, automations, keys or reports. | See Limits; wait Retry-After if present. |
| 409 | sites_in_use |
Fewer extra sites than the sites you already use. | Remove sites first. |
| 429 | credit_limit_reached |
The audit needs more credits than your plan has left this month. | Choose a smaller scope, wait for the next month, or upgrade. |
| 429 | spend_cap_reached |
The audit would go over your monthly spend cap. | Raise the cap, or wait for the next period. |
| 429 | rate_limited |
More requests a minute than your plan allows (Free 30, paid 120). | Wait Retry-After seconds (60). |
| 503 | billing_unavailable |
Payments are not open yet, or the payment service did not answer. | Try again later. |
| 503 | unavailable |
A temporary problem on our side. | Retry with backoff: 1 s, 2 s, 4 s… |
Retry or not
- Retry
429afterRetry-After, and503with backoff. - Retry a network error or a timeout of
POST /audit-runswith the sameIdempotency-Key: you get the same run, never a second audit. - Do not retry any other
4xxunchanged. It will fail the same way.
Errors of a run
An audit that started but could not finish is not an HTTP error: the run ends with status: failed and an errorCode. See Asynchronous audits.