Errors

Every error has the same shape:

{
  "error": {
    "type": "invalid_request",
    "code": "unknown_parameter",
    "message": "Unknown parameter 'bed'.",
    "param": "bed",
    "request_id": "req_4f1c2d9a8b7e6f5a4b3c2d1e",
    "doc_url": "https://platform.darak.app/docs/guides/errors#unknown-parameter"
  }
}

Branch on code: codes are never renamed, though new ones may be added. message is for humans and may change. Unknown query parameters are errors, not ignored, so typos surface immediately. Quote request_id when you contact us.

400 `invalid_request`

The request is wrong. Fix it; sending it again unchanged fails the same way.

invalid_value: A parameter's value isn't accepted. param names it.
missing_parameter: A required parameter was omitted. param names it.
unknown_parameter: No such parameter. Unknown ones are rejected, not ignored, so typos surface.
invalid_body: The JSON body was malformed or didn't match the schema.
unknown_city: That city isn't covered. GET /cities lists the slugs that are.
result_window_exceeded: Paging past your plan's depth. Narrow the query instead.
limit_reached: An account limit is already at its maximum.
invalid_cursor: The cursor is malformed, or belongs to a query with different filters or sort. Start the query again.

401 `authentication_error`

The key was missing, malformed or is no longer usable. Don't retry.

missing_api_key: No Authorization: Bearer header.
invalid_api_key: No key matches. Check for a truncated or wrong-environment key.
revoked_api_key: This key was revoked. Create a new one.
expired_api_key: This key passed its expiry date. Create a new one.
api_key_in_query: A key was passed in the URL, where it leaks into logs. Move it to the header and rotate it.

403 `permission_error`

The key is valid but isn't allowed this call. Don't retry.

scope_not_in_plan: Your plan doesn't include this API. Upgrade to reach it.
scope_not_in_key: Your plan includes this API but this key isn't allowed it. Edit the key.
admin_key_required: This endpoint needs an admin key (dk_admin_…).
admin_key_not_allowed: Admin keys only reach /v1/organization. Use a data key here.
forbidden_action: Your role in the organization doesn't allow this.
cr_outside_allowlist: That commercial registration isn't on your account's allowlist.
ip_not_allowed: Your organization's IP allowlist doesn't include this caller's address.
client_suspended: The account is suspended. Contact us.
client_expired: The account's term has ended. Contact us.

404 `not_found`

No such resource. For a listing, it may simply no longer be live.

not_found: No such resource.
city_not_found: No such city. GET /cities lists them.
route_not_found: No such endpoint. The spec is at /v1/openapi.json.
listing_not_found: No live listing with that id. It may have been delisted.
neighborhood_not_found: No such neighborhood in that city.
project_not_found: No such off-plan project.

405 `method_not_allowed`

Right path, wrong HTTP method. Allow lists the ones it takes.

method_not_allowed: That path exists, but not for this method.

409 `conflict`

The request can't be applied as things stand. Change it, then retry.

conflict: The resource's current state rules this out.
idempotency_key_reuse: This Idempotency-Key was already used with a different body. Use a new key.
key_limit: You already hold the most keys your plan allows. Revoke one first.
project_limit: You already hold the most projects your plan allows.
name_taken: Something with that name already exists.

429 `rate_limit_error`

Slow down. Retry-After says how long to wait.

rate_limited: Over your per-minute unit rate. Wait Retry-After seconds.
monthly_quota_exceeded: This month's unit quota is spent. It resets at the start of the next UTC month, or raise the spend cap.
spend_cap_reached: Extra usage hit the monthly spend cap an owner set. Raise it to continue.
project_cap_exceeded: This key's project hit its own monthly unit cap.

500 `api_error`

Our fault. Retry with exponential backoff.

internal_error: Something broke on our side. Retry with backoff; quote request_id if it lasts.

5xx errors are safe to retry with exponential backoff.

Errors

Every error has the same shape:

{
  "error": {
    "type": "invalid_request",
    "code": "unknown_parameter",
    "message": "Unknown parameter 'bed'.",
    "param": "bed",
    "request_id": "req_4f1c2d9a8b7e6f5a4b3c2d1e",
    "doc_url": "https://platform.darak.app/docs/guides/errors#unknown-parameter"
  }
}

400 `invalid_request`

The request is wrong. Fix it; sending it again unchanged fails the same way.

invalid_value: A parameter's value isn't accepted. param names it.
missing_parameter: A required parameter was omitted. param names it.
unknown_parameter: No such parameter. Unknown ones are rejected, not ignored, so typos surface.
invalid_body: The JSON body was malformed or didn't match the schema.
unknown_city: That city isn't covered. GET /cities lists the slugs that are.
result_window_exceeded: Paging past your plan's depth. Narrow the query instead.
limit_reached: An account limit is already at its maximum.
invalid_cursor: The cursor is malformed, or belongs to a query with different filters or sort. Start the query again.

401 `authentication_error`

The key was missing, malformed or is no longer usable. Don't retry.

missing_api_key: No Authorization: Bearer header.
invalid_api_key: No key matches. Check for a truncated or wrong-environment key.
revoked_api_key: This key was revoked. Create a new one.
expired_api_key: This key passed its expiry date. Create a new one.
api_key_in_query: A key was passed in the URL, where it leaks into logs. Move it to the header and rotate it.

403 `permission_error`

The key is valid but isn't allowed this call. Don't retry.

scope_not_in_plan: Your plan doesn't include this API. Upgrade to reach it.
scope_not_in_key: Your plan includes this API but this key isn't allowed it. Edit the key.
admin_key_required: This endpoint needs an admin key (dk_admin_…).
admin_key_not_allowed: Admin keys only reach /v1/organization. Use a data key here.
forbidden_action: Your role in the organization doesn't allow this.
cr_outside_allowlist: That commercial registration isn't on your account's allowlist.
ip_not_allowed: Your organization's IP allowlist doesn't include this caller's address.
client_suspended: The account is suspended. Contact us.
client_expired: The account's term has ended. Contact us.

404 `not_found`

No such resource. For a listing, it may simply no longer be live.

not_found: No such resource.
city_not_found: No such city. GET /cities lists them.
route_not_found: No such endpoint. The spec is at /v1/openapi.json.
listing_not_found: No live listing with that id. It may have been delisted.
neighborhood_not_found: No such neighborhood in that city.
project_not_found: No such off-plan project.

405 `method_not_allowed`

Right path, wrong HTTP method. Allow lists the ones it takes.

method_not_allowed: That path exists, but not for this method.

409 `conflict`

The request can't be applied as things stand. Change it, then retry.

conflict: The resource's current state rules this out.
idempotency_key_reuse: This Idempotency-Key was already used with a different body. Use a new key.
key_limit: You already hold the most keys your plan allows. Revoke one first.
project_limit: You already hold the most projects your plan allows.
name_taken: Something with that name already exists.

429 `rate_limit_error`

Slow down. Retry-After says how long to wait.

rate_limited: Over your per-minute unit rate. Wait Retry-After seconds.
monthly_quota_exceeded: This month's unit quota is spent. It resets at the start of the next UTC month, or raise the spend cap.
spend_cap_reached: Extra usage hit the monthly spend cap an owner set. Raise it to continue.
project_cap_exceeded: This key's project hit its own monthly unit cap.

500 `api_error`

Our fault. Retry with exponential backoff.

internal_error: Something broke on our side. Retry with backoff; quote request_id if it lasts.

5xx errors are safe to retry with exponential backoff.

Errors

400 invalid_request

401 authentication_error

403 permission_error

404 not_found

405 method_not_allowed

409 conflict

429 rate_limit_error

500 api_error

Errors

400 invalid_request

401 authentication_error

403 permission_error

404 not_found

405 method_not_allowed

409 conflict

429 rate_limit_error

500 api_error

400 `invalid_request`

401 `authentication_error`

403 `permission_error`

404 `not_found`

405 `method_not_allowed`

409 `conflict`

429 `rate_limit_error`

500 `api_error`

400 `invalid_request`

401 `authentication_error`

403 `permission_error`

404 `not_found`

405 `method_not_allowed`

409 `conflict`

429 `rate_limit_error`

500 `api_error`