Errors

DMLY uses conventional HTTP status codes. Anything in the 2xx range succeeded; 4xx means the request was wrong; 5xx means something broke on our side. Every error returns the same envelope (a missing-permission 403 adds a required_scope field):

{ "message": "No query results for model [Contact]." }

Validation errors add a per-field breakdown:

{
  "message": "The name field is required.",
  "errors": {
    "name":  ["The name field is required."],
    "email": ["The email must be a valid email address."]
  }
}

Status codes

Code	Meaning	What to do
`401`	Missing, invalid, or revoked API key, or its workspace was deleted	Check the key. Do not retry as-is
`400`	The `Idempotency-Key` header is empty or longer than 255 characters	Fix the header
`403`	The key lacks the permission for this area, the workspace has no active subscription, or it has been suspended	See A note on 403
`409`	A request with the same `Idempotency-Key` is still being processed	Wait and retry, honour `Retry-After`
`404`	No such resource in this workspace	Check the id, and that the key belongs to the right workspace
`422`	Validation failed, or an `Idempotency-Key` was reused for a different request	Read `errors` and fix the request, or use a new key
`429`	Rate limit exceeded	Back off, honour `Retry-After`
`5xx`	Something broke on our side	Retry with backoff; if it persists, get in touch

A note on 403

A 403 has one of three causes:

The key lacks a permission. The body names it, for example {"message": "This API key does not have the \"contacts:write\" permission. Create a key that includes it.", "required_scope": "contacts:write"}. Create a key that includes that area. An endpoint outside every area needs a key with Full access.
The subscription has ended. The body is This workspace has no active subscription. and it applies to every request, reads included. Paying again restores access. A workspace that is only past due keeps working over the API.
The workspace is suspended: either it was locked, or it is an agency sub-account whose agency is no longer active. Whoever suspended it has to lift it: the agency for a sub-account, otherwise get in touch.

A note on 404

The API is workspace-scoped by the key. A resource that exists but belongs to a different workspace returns 404, not 403; from your key’s point of view it genuinely does not exist. If you are certain an id is valid and still get 404, you are almost always using a key from the wrong workspace.

Retrying safely

GET and DELETE are idempotent, so retry freely. POST is not, unless you send an Idempotency-Key header. A create that times out may still have succeeded, so a blind retry can produce a duplicate. Send Idempotency-Key with a unique value (1 to 255 characters) on each write. A repeat with the same key, method, path, query and body within 24 hours returns the first answer again, with the header Idempotent-Replayed: true, instead of creating a second record. A repeat while the first is still running gets 409 with Retry-After: 2. Reusing a key for a different request gets 422. Answers of 408, 409, 425, 429 and 5xx are not stored, so retrying one runs the request again. Without the header, search for the record before retrying a POST, or key off something unique (a contact’s phone number).

Retry 409, 429 and 5xx with backoff. Never retry 401, 403, or 422 unchanged; the same request will fail identically every time.

Getting started

Endpoints

Webhook events

Status codes

A note on 403

A note on 404

Retrying safely

​Status codes

​A note on 403

​A note on 404

​Retrying safely

Status codes

A note on 403

A note on 404

Retrying safely