Errors and limits | Integrations

This page is for the developer writing the code that calls InMyWords and handles its answers.

It lists every error code, the limits on calls and on the addresses they come from, the rules for retrying a change safely, and how to read a list page by page.

Errors

An error answers an HTTP status and a body:

{
  "error": {
    "code": "scope_missing",
    "message": "This connection does not hold cases:write."
  }
}

code is stable, and it is what your program should read. message is written for a person and may change.

Every answer, error or not, carries an X-Request-Id header of 16 hex characters. Quote it when you ask us about a call.

Status	Code	Meaning
400	`invalid_request`	the request cannot be read: malformed JSON, a wrong type, or a bad `limit`, `cursor` or `updated_since`
401	`unauthorised`	the key is missing, malformed or revoked
403	`module_off`	the Integrations module is off for your organisation, or its integrations data policy has not been accepted
403	`ip_not_allowed`	your organisation allows calls only from the addresses it has listed, and this is not one
403	`scope_missing`	the connection does not hold the scope the call needs
403	`permission_not_grantable`	the call would give a group Manage users, Manage billing, Manage integrations or Manage groups, or put a person in a group that holds one
404	`not_found`	there is no such thing, or it belongs to another organisation
409	named per endpoint	the change conflicts with the state of your organisation, for example `last_people_manager`, `group_holds_cases`, `in_another_organisation`
409	`idempotency_key_in_use`	a request with the same `Idempotency-Key` is still being answered; retry after `Retry-After` seconds
422	`validation_failed`	the request was read but a value is not allowed; the message names the field
422	`unknown_permission`	a permission code that does not exist
422	`idempotency_key_reused`	an `Idempotency-Key` already used for a different request: another body, address or method
429	`rate_limited`	the connection has made more calls this minute than it is allowed, or too many refused calls came from one address
500	`server_error`	a fault at InMyWords; nothing was changed unless the answer says otherwise

How many calls you can make

A connection can make 120 calls a minute by default. InMyWords sets the figure.

Calls are counted per clock minute, from second 0 to second 59. A call over the limit answers 429 rate_limited with a Retry-After header, in seconds.

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-Request-Id: 3f9a1c0e7b2d4e6f

{
  "error": {
    "code": "rate_limited",
    "message": "Too many calls this minute."
  }
}

Calls refused with 429 still count towards the minute.

Calls from one address that are refused 401 are counted too. After 60 in a minute, every call from that address, with any key, answers 429 rate_limited until the minute ends.

Which addresses calls may come from

Your organisation can list the addresses its people may reach InMyWords from. Its connections are held to the same list.

Where your organisation enforces its list, a call from an address not on it answers 403 ip_not_allowed.
Where it only reports, the call is answered, and your organisation's audit trail records the address under the connection's name.

Ask for the addresses your other software calls from to be added to the list.

Sending a change only once

Every POST takes an Idempotency-Key header of up to 255 characters. A random UUID makes a good key.

The key is kept for 24 hours, per connection.
Same key, same address, same body. Within 24 hours you get the first result back, with its status and an Idempotent-Replayed: true header, and nothing changes.
Same key, different body, address or method. This answers 422 idempotency_key_reused.
Same key while the first is still being answered. This answers 409 idempotency_key_in_use with Retry-After: 1. Only one of the two is carried out.
A request that failed with a 5xx keeps nothing. You can send the same key again, and it is carried out.
Something shown once is not shown again. An answer that showed something once, such as a webhook's secret, is replayed without it.
No key. The POST is carried out every time it is sent.

curl -X POST https://app.inmywords.chat/api/integrations/v1/cases \
  -H "Authorization: Bearer imw_3f9a0c2e7b1d4a6f8e0c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6d1f0b7a-2c44-4f0e-9a3b-1e5c7d9f2a10" \
  -d '{"title": "Housing claim", "external_ref": "CMS-20931"}'

When to retry

Answer	Retry
429	yes, after `Retry-After` seconds
500, or no answer	yes, with the same `Idempotency-Key` for a POST
409 `idempotency_key_in_use`	yes, after `Retry-After` seconds, with the same key
400, 401, 403, 404, other 409, 422	no; the same request gets the same answer

Reading a long list

A list answers {"data": [...], "next_cursor": "..."}, newest first. limit is 50 by default and 100 at most, and a larger value is reduced to 100. A limit that is not a whole number from 1 answers 400 invalid_request.

To read the next page, pass next_cursor back as cursor. A null cursor means you have the last page. A cursor is opaque, so do not build or change one.

To fetch only what has changed, give updated_since an ISO 8601 UTC time, for example 2026-10-03T14:05:00Z, and you get back only what changed after it. Each list says what counts as a change. A list that does not offer updated_since answers 400 invalid_request.

A bad cursor or updated_since answers 400 invalid_request.

curl "https://app.inmywords.chat/api/integrations/v1/conversations?limit=100&cursor=eyJiIjo4ODEyfQ&updated_since=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer imw_3f9a0c2e7b1d4a6f8e0c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a"

What is logged

Every call is logged against the connection, with its method, address, status and time taken. Your organisation can read the log on the connection's page.

Every change, and every read of a conversation's words, is also written on your organisation's audit trail under the connection's name.