Errors always come as RFC 9457 application/problem+json:
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
{
"type": "https://docs.grem.capital/api/errors/business_rule",
"title": "business_rule",
"status": 422,
"detail": "Describe the property: pick a listing or fill in at least a description, city or area",
"code": "not_enough_input",
"requestId": "req_..."
}
| Field | Content |
|---|---|
status | HTTP status |
title | stable error code (list below) - branch on it |
detail | human-readable explanation; do not parse it, the wording may change |
code | machine code of the specific reason, when known (not_enough_input, INSUFFICIENT_FUNDS, ...) |
errors | field-level problems: { "field", "message" }, plus code when known |
requestId | request id - quote it when contacting support |
A validation error with fields:
{
"title": "validation",
"status": 400,
"detail": "\"avatarId\" is required",
"errors": [{ "field": "avatarId", "message": "\"avatarId\" is required" }],
"requestId": "req_..."
}
Error codes
The type URL leads to the matching entry of this list.
invalid_key
401. The key is missing, wrong, revoked or expired. Check the Authorization header and the key status in the cabinet.
forbidden_scope
403. The key is valid but lacks the required scope. Grant the scope or create a new key (Authentication).
forbidden
403. The action is not allowed for this account or resource: for example the listing belongs to another account or the agency role is too low. The reason is in detail.
insufficient_funds
402. Not enough money in the wallet, the plan quota is used up, there is an unpaid debt or the fair-use limit is reached. code says which: INSUFFICIENT_FUNDS, QUOTA_EXCEEDED, DEBT_OUTSTANDING, FAIR_USE_LIMIT_REACHED and so on. Top up, pay the debt or change the plan.
validation
400. The request failed validation. What exactly is wrong is in detail and errors. Fix the request; repeating it unchanged is pointless.
business_rule
422. The request is well-formed but cannot be done: data is missing, the listing is in the wrong state, the property type is not supported and so on. The reason is in detail, the machine code in code.
payload_too_large
413. The request body or a file is over the limit. Size limits are listed with each tool. A body that is not valid JSON is 400 validation.
range_not_satisfiable
416. The Range of a file download is outside the file. Content-Range: bytes */size gives the file size.
rate_limited
429. Rate limit exceeded. Wait as many seconds as Retry-After says, then retry (Limits and billing). code says which limit: minute_limit (seconds) or daily_limit (resets at 00:00 UTC).
not_found
404. Unknown path, or a resource that does not exist or is not yours. Someone else's resource deliberately gets the same answer as a missing one.
idempotency_conflict
409. A request with this Idempotency-Key is still running. Wait for it to finish and retry with the same key (Idempotency). After a timeout (502 provider_error) the key is held for 15 minutes: check the result before repeating - a repeat after the hold runs the paid work again. The express valuation releases the key after a timeout: repeat it with the same key. The same 409 comes when the payment for a call with this key is still being reserved (code RESERVE_IN_PROGRESS, RESERVE_BUSY) - retry later; RESERVE_REF_TAKEN - the key is used up, send a new one.
conflict
409. The resource is in a state that does not allow this action (for example, moving a listing between agencies, deleting a listing with an active commission contract). The reason is in detail. Do not repeat the request unchanged.
service_unavailable
503. The tool is temporarily unavailable. Nothing was charged. Retry after the Retry-After pause; GET /tools/status shows the current state of the tools.
provider_error
502. The service doing the work failed. Temporary: retry with a growing pause. If detail says the tool did not answer in time, the work may still finish and be charged: check GET /works before starting it again; repeat the express valuation with the same Idempotency-Key. Photo enhancement, site and draft results are not kept in GET /works: for them wait out the 15-minute hold and check the result in the cabinet or among your listings.
internal_error
500. Internal error. Retry with a pause; if it keeps happening, contact support with the requestId.
The list may grow. Treat an unknown code as a generic error of its HTTP class (4xx - request problem, 5xx - service failure).
What to retry
| Status | Retry? |
|---|---|
400, 401, 403, 404, 413, 416, 422 | no - fix the request, key or data first |
402 | after topping up |
409 idempotency_conflict | yes, with the same Idempotency-Key, once the first request finishes. After a timeout (provider_error) the key is held for 15 minutes: check the result first - a repeat after the hold runs the paid work again; the express valuation releases the key, repeat it with the same key |
409 conflict | no - change the state of the resource first |
429, 503 | yes, after Retry-After seconds |
500, 502 | yes, with a growing pause (1, 2, 4, 8 ... seconds) |
When retrying requests that create something, always send the same Idempotency-Key - the retry will then neither run nor charge the work twice.
Exceptions
- Swipe Match events (
POST /match/leads/{id}/events) not allowed by the lead's current state answer409withtitle: business_ruleand the reason incode(client_event_rejected,invalid_transition,not_available). - Agency lead-pool actions (
POST /leads/{id}/claim,POST /leads/{id}/return-to-pool) with a personal key or an insufficient role answer403withtitle: forbidden.
What is not charged
A refused request (any 4xx or 5xx answer) does not use an API call. The tool price is charged only for accepted work. The exception is provider_error after a timeout: the work may still finish and be charged - check GET /works before starting it again (photo enhancement, site and draft: the cabinet or your listings).