Estimate a job
POST/estimates
10 credits for text or a conversation, 25 with photos. A priced, needs_detail, unsupported or unclear answer spends them; any 4xx or 5xx does not. A test key never spends credits; input.text starting with sandbox: answers from the sandbox.
Request
Responses
- 200
- 202
- default
The estimate.
Response Headers
The id of this request. Quote it when you contact support.
The API version that answered: the one the request named, or the version the account is pinned to.
The per-minute limit of the account, as limit;w=60.
Requests left in the current minute: limit, remaining and reset in seconds.
Present when the answer is the stored answer of an earlier request with the same Idempotency-Key.
Accepted, with mode async: the estimate is processing. It finishes in the background, usually within a minute.
Response Headers
The id of this request. Quote it when you contact support.
The API version that answered: the one the request named, or the version the account is pinned to.
The per-minute limit of the account, as limit;w=60.
Requests left in the current minute: limit, remaining and reset in seconds.
Credits held for an async estimate until it finishes; spent if it answers, given back if it fails. Zero for a test key.
Present when the answer is the stored answer of an earlier request with the same Idempotency-Key.
Every error is a problem details body; code says which.
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_request | The request is malformed. |
| 401 | api_key_missing | The request has no API key. |
| 401 | api_key_invalid | The key does not match any Hometown key. |
| 401 | api_key_revoked | The key was revoked and no longer works. |
| 401 | api_key_expired | The key was rotated and its 7-day overlap period ended. |
| 402 | insufficient_credits | The balance does not cover the credits this request needs. |
| 402 | monthly_cap_reached | The account reached the monthly credit cap set in the dashboard. |
| 403 | scope_missing | The key lacks the scope this operation requires, or the operation belongs to the Records add-on, which the account does not have. |
| 403 | tenant_suspended | The account is pending activation or suspended, and every key of the account is refused. |
| 403 | terms_not_accepted | The account has not accepted the current API Terms and Data Processing Agreement, and the 30 days after they took effect are over. |
| 403 | ip_not_allowed | The request came from an IP address outside the allowlist of the key. |
| 403 | api_key_paused | The key is paused because its activity looked unlike its usual traffic. |
| 403 | test_key_on_live_route | This operation accepts only a live key. |
| 409 | idempotency_conflict | A request with the same Idempotency-Key is still in progress. |
| 413 | payload_too_large | The request body exceeds 30 MB for POST /v1/estimates or 1 MB for any other operation, or one image exceeds 5 MB. |
| 415 | unsupported_media_type | An image is not JPEG, PNG or WebP. |
| 422 | validation_failed | A parameter has a value outside its rules. |
| 422 | idempotency_key_reused | The Idempotency-Key was already used with a different body within the last 24 hours. |
| 422 | content_rejected | The text or an image did not pass content moderation. |
| 422 | sandbox_input_on_live | Inputs that start with sandbox: work only with a test key. |
| 422 | unsupported_in_region | Hometown does not price this job in the requested region. |
| 422 | webhook_url_rejected | Hometown does not deliver to this URL. |
| 422 | webhook_endpoint_limit | The environment already has 16 active webhook endpoints, the most it can have. |
| 422 | event_not_redeliverable | The event is older than 30 days. |
| 422 | records_cap_reached | The environment already keeps 50,000 customers and records, counted together, the most it can keep. |
| 422 | billing_profile_incomplete | The billing profile lacks the legal name, address or country that tax calculation requires. |
| 422 | pack_unknown | The pack value is not in the catalog. |
| 429 | rate_limited | The key exceeded the per-minute limit of the account. |
| 429 | daily_quota_reached | The account reached its daily request limit. |
| 429 | sandbox_daily_cap_reached | The test keys of an account make up to 200 estimates a day together, sandbox inputs included. |
| 500 | internal_error | The request failed inside Hometown. |
| 503 | model_unavailable | The estimator did not answer in time. |
| 503 | service_unavailable | The API is in maintenance or cannot respond. |
Response Headers
The id of this request. Quote it when you contact support.
The API version that answered: the one the request named, or the version the account is pinned to.