Errors

Every error has the same shape and a stable code. Branch on the code: messages may be reworded.

{
  "error": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the bills:read scope.",
    "request_id": "req_3f2a9c1d7b8e4f60a1b2c3d4e5f60718",
    "required_scope": "bills:read",
    "doc_url": "https://developers.doolae.online/docs/guides/errors#insufficient_scope"
  }
}

An ID that belongs to another landlord's account gets exactly the same 404 resource_not_found as an ID that doesn't exist.

400 Bad Request

invalid_request

The request couldn't be understood. Check the method, path and body.

invalid_json

The body isn't valid JSON.

unknown_parameter

A query parameter or body field the endpoint doesn't accept. param names it. Fields like id or status: "paid" are never accepted in a body.

invalid_parameter

A parameter has an invalid value: wrong type, out of range, wrong format. param names it, and message says why.

invalid_cursor

The pagination cursor was changed, or belongs to a request with a different order. Start again without cursor.

api_key_in_query

The key was sent in the URL. Send it in the Authorization header, and rotate the exposed key.

invalid_idempotency_key

Idempotency-Key must be 1–255 printable ASCII characters.

account_header_invalid

DOOLAE-Account must be an account ID such as acct_….

401 Unauthorized

missing_api_key

No Authorization: Bearer … header was sent.

invalid_api_key

The key is malformed or unknown.

api_key_revoked

The key was revoked, its application was deleted, or the developer account was closed.

api_key_expired

The key reached its expiry date, or the 24 hours after a rotation have passed. Use the new key.

402 Payment Required

payment_required

Live mode only: an invoice for your developer account is overdue. Pay it under Billing in the portal. Test mode keeps working.

403 Forbidden

insufficient_scope

The key, the application or the landlord's grant doesn't include the scope in required_scope.

account_required

This live key isn't bound to one account. Send DOOLAE-Account: acct_….

account_not_connected

That account isn't linked to this application (or doesn't exist: the answer is the same), or a test key was used with another account. Knowing an account ID never grants access.

account_access_revoked

The landlord disconnected your application. Ask them to connect again if they want to.

account_mismatch

The key is bound to a different account than the one in DOOLAE-Account.

developer_suspended

DOOLAE suspended your developer account. Contact support.

application_disabled

DOOLAE disabled this application. Contact support.

origin_not_allowed

A browser request came from an origin the application doesn't allow. See security.

test_mode_only

The endpoint (for example /v1/test-helpers/payments) only works with a test key.

plan_limit_reached

The landlord's DOOLAE plan doesn't allow more properties, rooms or tenants. The landlord can upgrade at doolae.online.

feature_not_available

The landlord's DOOLAE plan doesn't include the feature, for example LINE messages.

404 Not Found

resource_not_found

No such object in this account.

route_not_found

No endpoint exists at this path. Check the path and the /v1 prefix.

405 Method Not Allowed

method_not_allowed

The path exists, but not with this method. The Allow header lists the methods it supports.

409 Conflict

conflict

Something changed at the same moment (for example a payment arrived). Fetch the object again and retry.

idempotency_in_progress

A request with this Idempotency-Key is still running. Retry shortly.

resource_exists

A meter reading or bill already exists for that room and month. existing_id points to it.

room_number_taken

The property already has a room with that number.

room_occupied

The room already has a tenant. Move them out first.

room_has_no_tenant

A bill needs a tenant in the room.

reading_required

Record the month's meter reading before creating its bill.

reading_locked

The month's bill is paid, so its reading can't change.

bill_locked

The bill is paid and can't change.

bill_not_payable

The bill can't be paid now: it is a draft, or QR payments aren't available for this landlord.

property_not_empty

Only a property without rooms can be deleted through the API.

413, 415, 422

request_too_large

The body is over 1 MB.

unsupported_media_type

Send bodies as Content-Type: application/json.

idempotency_key_reused

This Idempotency-Key was used with a different request. Use a new key for a new operation.

invalid_reading

A meter value is lower than the previous one, or the water value is missing for metered water. If a meter was replaced, send previous explicitly.

429 Too Many Requests

rate_limited

Over your per-second limit. Wait Retry-After seconds. See rate limits.

monthly_quota_exceeded

The Free plan's monthly requests are used up. They reset on the 1st; or upgrade.

too_many_failed_attempts

Too many requests with invalid keys came from your IP address. Wait a minute and check your key.

sending_limit

Too many LINE messages for this account in the last minute. Wait Retry-After seconds.

sandbox_limit

The sandbox is full (20 properties, 500 rooms), or you made 20,000 test requests today. Reset the sandbox in the portal.

500 and 503

internal_error

Something went wrong on DOOLAE's side and has been logged. Retry with backoff; contact support with the request_id if it persists.

service_unavailable

DOOLAE is briefly overloaded, or a dependency (such as LINE) is unavailable. Retry after Retry-After seconds.

timeout

The request took longer than 25 seconds. If it was a write, retry with the same Idempotency-Key: you will get its real result once it finishes.

api_not_configured

The server is missing its API configuration. This should never happen in production; contact support.