@productcraft/notify 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/api.md CHANGED
@@ -22,7 +22,8 @@ At most 50 categories per workspace during the preview. Channels left out of `de
22
22
  | Status | Error class | Codes | When |
23
23
  |---|---|---|---|
24
24
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid (`errors` names it). |
25
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
25
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
26
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
26
27
  | 409 | `ConflictError` | `CONFLICT`, `CATEGORY_KEY_TAKEN`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `CATEGORY_KEY_TAKEN`: the key is in use; `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was used with a different body. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
27
28
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `LIMIT_EXCEEDED` | `LIMIT_EXCEEDED`: the workspace already has 50 categories. |
28
29
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
@@ -45,7 +46,8 @@ Only when no notification type uses it. Recipients' preferences for the category
45
46
 
46
47
  | Status | Error class | Codes | When |
47
48
  |---|---|---|---|
48
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
49
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
50
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
49
51
  | 404 | `NotFoundError` | `NOT_FOUND`, `CATEGORY_NOT_FOUND` | `CATEGORY_NOT_FOUND`: no category with this id in this workspace. |
50
52
  | 409 | `ConflictError` | `CONFLICT`, `CATEGORY_IN_USE` | `CATEGORY_IN_USE`: a notification type still uses the category. |
51
53
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
@@ -71,7 +73,8 @@ By `ordinal`, then oldest first.
71
73
  | Status | Error class | Codes | When |
72
74
  |---|---|---|---|
73
75
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR` on a bad parameter, or `BAD_REQUEST`: invalid cursor. |
74
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
76
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
77
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
75
78
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
76
79
 
77
80
  ```ts
@@ -93,7 +96,8 @@ Get a category.
93
96
 
94
97
  | Status | Error class | Codes | When |
95
98
  |---|---|---|---|
96
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
99
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
100
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
97
101
  | 404 | `NotFoundError` | `NOT_FOUND`, `CATEGORY_NOT_FOUND` | `CATEGORY_NOT_FOUND`: no category with this id in this workspace. |
98
102
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
99
103
 
@@ -117,7 +121,8 @@ Changes the fields you send. `defaults` merges per channel. The key cannot chang
117
121
  | Status | Error class | Codes | When |
118
122
  |---|---|---|---|
119
123
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid (`errors` names it). |
120
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
124
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
125
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
121
126
  | 404 | `NotFoundError` | `NOT_FOUND`, `CATEGORY_NOT_FOUND` | `CATEGORY_NOT_FOUND`: no category with this id in this workspace. |
122
127
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
123
128
 
@@ -141,7 +146,8 @@ Whether each channel (inbox, email, push, web push) can deliver now, and the met
141
146
 
142
147
  | Status | Error class | Codes | When |
143
148
  |---|---|---|---|
144
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
149
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
150
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
145
151
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
146
152
 
147
153
  ```ts
@@ -164,7 +170,8 @@ Deletes an APNs credential and erases its key immediately. Push to devices of it
164
170
 
165
171
  | Status | Error class | Codes | When |
166
172
  |---|---|---|---|
167
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
173
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
174
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
168
175
  | 404 | `NotFoundError` | `NOT_FOUND`, `CREDENTIAL_NOT_FOUND` | `CREDENTIAL_NOT_FOUND`: no APNs credential with this id in the workspace. |
169
176
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
170
177
 
@@ -189,7 +196,8 @@ Uploads an APNs authentication key (`.p8`, token auth) for one bundle id. You st
189
196
  | Status | Error class | Codes | When |
190
197
  |---|---|---|---|
191
198
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is malformed (`errors` names it). |
192
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
199
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
200
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
193
201
  | 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `CONFLICT`: another upload for the same bundle id ran at the same time; `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was used with a different body. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
194
202
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `CREDENTIAL_INVALID`, `CREDENTIAL_MISMATCH` | `CREDENTIAL_INVALID`: the `.p8` is not a P-256 private key, or Apple rejected it (wrong `key_id`/`team_id`, revoked key); `CREDENTIAL_MISMATCH`: Apple accepted the key but not for this `bundle_id`. Nothing was stored. |
195
203
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
@@ -221,7 +229,8 @@ Deletes an FCM credential and erases its private key immediately. Push to Androi
221
229
 
222
230
  | Status | Error class | Codes | When |
223
231
  |---|---|---|---|
224
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
232
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
233
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
225
234
  | 404 | `NotFoundError` | `NOT_FOUND`, `CREDENTIAL_NOT_FOUND` | `CREDENTIAL_NOT_FOUND`: no FCM credential with this id in the workspace. |
226
235
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
227
236
 
@@ -246,7 +255,8 @@ Uploads the JSON key of a Google service account for one Firebase project (FCM H
246
255
  | Status | Error class | Codes | When |
247
256
  |---|---|---|---|
248
257
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is malformed (`errors` names it). |
249
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
258
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
259
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
250
260
  | 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `CONFLICT`: another upload for the same project ran at the same time; `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was used with a different body. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
251
261
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `CREDENTIAL_INVALID` | `CREDENTIAL_INVALID`: the JSON is not a service-account key file, or Google rejected it (deleted account or key, missing Firebase Cloud Messaging role, FCM API not enabled, unknown project). Nothing was stored. |
252
262
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
@@ -275,7 +285,8 @@ Generates a P-256 key pair for web push (RFC 8292) and returns its public key; t
275
285
  | Status | Error class | Codes | When |
276
286
  |---|---|---|---|
277
287
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid (`errors` names it). |
278
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
288
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
289
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
279
290
  | 409 | `ConflictError` | `CONFLICT`, `CONFIRMATION_REQUIRED`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `CONFIRMATION_REQUIRED`: the workspace already has a VAPID key and the body has no `confirm: "rotate"`; `CONFLICT`: another request changed the key at the same time; `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was used with a different body. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
280
291
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
281
292
 
@@ -299,7 +310,8 @@ Imports an existing VAPID key pair (for example from another push provider) so s
299
310
  | Status | Error class | Codes | When |
300
311
  |---|---|---|---|
301
312
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid (`errors` names it). |
302
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
313
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
314
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
303
315
  | 409 | `ConflictError` | `CONFLICT`, `CONFIRMATION_REQUIRED` | `CONFIRMATION_REQUIRED`: a different key is active and the body has no `confirm: "rotate"`; `CONFLICT`: another request changed the key at the same time. |
304
316
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `CREDENTIAL_INVALID` | `CREDENTIAL_INVALID`: the keys are not base64url P-256 keys, or they are not a matching pair. |
305
317
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
@@ -325,7 +337,8 @@ The VAPID public key browsers subscribe with (`applicationServerKey`), or `confi
325
337
 
326
338
  | Status | Error class | Codes | When |
327
339
  |---|---|---|---|
328
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
340
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
341
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
329
342
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
330
343
 
331
344
  ```ts
@@ -351,7 +364,8 @@ Newest first. Filter by `notification_id`, `recipient` (external id), `state` or
351
364
  | Status | Error class | Codes | When |
352
365
  |---|---|---|---|
353
366
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR` on a bad filter, or `BAD_REQUEST`: invalid cursor. |
354
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
367
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
368
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
355
369
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
356
370
 
357
371
  ```ts
@@ -375,7 +389,8 @@ With every provider attempt (status, code, duration; no message content).
375
389
 
376
390
  | Status | Error class | Codes | When |
377
391
  |---|---|---|---|
378
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
392
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
393
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
379
394
  | 404 | `NotFoundError` | `NOT_FOUND`, `DELIVERY_NOT_FOUND` | `DELIVERY_NOT_FOUND`: no delivery with this id in this workspace. |
380
395
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
381
396
 
@@ -399,7 +414,8 @@ Categories, notification types with every template, and settings, in the shapes
399
414
 
400
415
  | Status | Error class | Codes | When |
401
416
  |---|---|---|---|
402
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
417
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
418
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
403
419
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
404
420
 
405
421
  ```ts
@@ -422,7 +438,8 @@ Archived types cannot be sent (`NOTIFICATION_TYPE_ARCHIVED`); history stays. Arc
422
438
 
423
439
  | Status | Error class | Codes | When |
424
440
  |---|---|---|---|
425
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
441
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
442
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
426
443
  | 404 | `NotFoundError` | `NOT_FOUND`, `NOTIFICATION_TYPE_NOT_FOUND` | `NOTIFICATION_TYPE_NOT_FOUND`: no notification type with this id in this workspace. |
427
444
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
428
445
 
@@ -447,7 +464,8 @@ At most 200 types per workspace during the preview. Add templates with `PUT …/
447
464
  | Status | Error class | Codes | When |
448
465
  |---|---|---|---|
449
466
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid (`errors` names it). |
450
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
467
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
468
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
451
469
  | 409 | `ConflictError` | `CONFLICT`, `NOTIFICATION_TYPE_KEY_TAKEN`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `NOTIFICATION_TYPE_KEY_TAKEN`: the key is in use; `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was used with a different body. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
452
470
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `CATEGORY_NOT_FOUND`, `VALIDATION_ERROR`, `LIMIT_EXCEEDED` | `CATEGORY_NOT_FOUND`: no category with `category_key`; `VALIDATION_ERROR`: the routing is invalid; `LIMIT_EXCEEDED`: the workspace already has 200 types. |
453
471
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
@@ -473,7 +491,8 @@ Newest first; archived types only with `include_archived=true`.
473
491
  | Status | Error class | Codes | When |
474
492
  |---|---|---|---|
475
493
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR` on a bad parameter, or `BAD_REQUEST`: invalid cursor. |
476
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
494
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
495
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
477
496
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
478
497
 
479
498
  ```ts
@@ -499,7 +518,8 @@ Renders every routed channel with sample `data`, or as a real `recipient` (its l
499
518
  | Status | Error class | Codes | When |
500
519
  |---|---|---|---|
501
520
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid. |
502
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
521
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
522
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
503
523
  | 404 | `NotFoundError` | `NOT_FOUND`, `NOTIFICATION_TYPE_NOT_FOUND`, `RECIPIENT_NOT_FOUND` | `NOTIFICATION_TYPE_NOT_FOUND`, or `RECIPIENT_NOT_FOUND`: no recipient with this external id. |
504
524
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
505
525
 
@@ -523,7 +543,8 @@ Types as code: sets the type and its complete template set in one transaction (t
523
543
  | Status | Error class | Codes | When |
524
544
  |---|---|---|---|
525
545
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field or template entry is invalid. |
526
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
546
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
547
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
527
548
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `CATEGORY_NOT_FOUND`, `VALIDATION_ERROR`, `TEMPLATE_INVALID`, `UNSAFE_URL`, `LIMIT_EXCEEDED` | `CATEGORY_NOT_FOUND`, `VALIDATION_ERROR` (routing), `TEMPLATE_INVALID`, `UNSAFE_URL` or `LIMIT_EXCEEDED` (200 types, 32 KB per template). |
528
549
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
529
550
 
@@ -543,7 +564,8 @@ Get a notification type.
543
564
 
544
565
  | Status | Error class | Codes | When |
545
566
  |---|---|---|---|
546
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
567
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
568
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
547
569
  | 404 | `NotFoundError` | `NOT_FOUND`, `NOTIFICATION_TYPE_NOT_FOUND` | `NOTIFICATION_TYPE_NOT_FOUND`: no notification type with this id in this workspace. |
548
570
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
549
571
 
@@ -567,7 +589,8 @@ Changes the fields you send; `routing` is replaced whole. The key cannot change.
567
589
  | Status | Error class | Codes | When |
568
590
  |---|---|---|---|
569
591
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid. |
570
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
592
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
593
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
571
594
  | 404 | `NotFoundError` | `NOT_FOUND`, `NOTIFICATION_TYPE_NOT_FOUND` | `NOTIFICATION_TYPE_NOT_FOUND`: no notification type with this id in this workspace. |
572
595
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `CATEGORY_NOT_FOUND`, `VALIDATION_ERROR` | `CATEGORY_NOT_FOUND`: no category with `category_key`; `VALIDATION_ERROR`: the routing is invalid. |
573
596
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
@@ -593,7 +616,8 @@ Deletes the template and its versions. Sends to that channel and locale fall bac
593
616
  | Status | Error class | Codes | When |
594
617
  |---|---|---|---|
595
618
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: unknown channel or malformed locale. |
596
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
619
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
620
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
597
621
  | 404 | `NotFoundError` | `NOT_FOUND`, `NOTIFICATION_TYPE_NOT_FOUND`, `TEMPLATE_NOT_FOUND` | `NOTIFICATION_TYPE_NOT_FOUND`, or `TEMPLATE_NOT_FOUND`: the type has no template for this channel and locale. |
598
622
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
599
623
 
@@ -614,7 +638,8 @@ Get a template.
614
638
  | Status | Error class | Codes | When |
615
639
  |---|---|---|---|
616
640
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: unknown channel or malformed locale. |
617
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
641
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
642
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
618
643
  | 404 | `NotFoundError` | `NOT_FOUND`, `NOTIFICATION_TYPE_NOT_FOUND`, `TEMPLATE_NOT_FOUND` | `NOTIFICATION_TYPE_NOT_FOUND`, or `TEMPLATE_NOT_FOUND`: the type has no template for this channel and locale. |
619
644
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
620
645
 
@@ -638,7 +663,8 @@ Restores an earlier version as a new version (audited as `notify.template.revert
638
663
  | Status | Error class | Codes | When |
639
664
  |---|---|---|---|
640
665
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: unknown channel, malformed locale or version. |
641
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
666
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
667
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
642
668
  | 404 | `NotFoundError` | `NOT_FOUND`, `NOTIFICATION_TYPE_NOT_FOUND`, `TEMPLATE_NOT_FOUND`, `TEMPLATE_VERSION_NOT_FOUND` | `NOTIFICATION_TYPE_NOT_FOUND`, `TEMPLATE_NOT_FOUND`, or `TEMPLATE_VERSION_NOT_FOUND`: that version is not kept. |
643
669
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
644
670
 
@@ -662,7 +688,8 @@ Sets the template of one channel and locale. Every change is kept as a version (
662
688
  | Status | Error class | Codes | When |
663
689
  |---|---|---|---|
664
690
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: unknown channel or malformed locale. |
665
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
691
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
692
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
666
693
  | 404 | `NotFoundError` | `NOT_FOUND`, `NOTIFICATION_TYPE_NOT_FOUND` | `NOTIFICATION_TYPE_NOT_FOUND`: no notification type with this id in this workspace. |
667
694
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `TEMPLATE_INVALID`, `UNSAFE_URL`, `LIMIT_EXCEEDED` | `TEMPLATE_INVALID`: a field is missing, unknown or does not parse (the message names it); `UNSAFE_URL`: a URL field is not https; `LIMIT_EXCEEDED`: the template is over 32 KB or the type has 100 templates. |
668
695
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
@@ -686,7 +713,8 @@ The last 20 versions, newest first.
686
713
  | Status | Error class | Codes | When |
687
714
  |---|---|---|---|
688
715
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: unknown channel or malformed locale. |
689
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
716
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
717
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
690
718
  | 404 | `NotFoundError` | `NOT_FOUND`, `NOTIFICATION_TYPE_NOT_FOUND`, `TEMPLATE_NOT_FOUND` | `NOTIFICATION_TYPE_NOT_FOUND`, or `TEMPLATE_NOT_FOUND`: the type has no template for this channel and locale. |
691
719
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
692
720
 
@@ -710,7 +738,8 @@ Deliveries still pending, scheduled or retrying end `skipped: cancelled`, and re
710
738
 
711
739
  | Status | Error class | Codes | When |
712
740
  |---|---|---|---|
713
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
741
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
742
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
714
743
  | 404 | `NotFoundError` | `NOT_FOUND`, `NOTIFICATION_NOT_FOUND` | `NOTIFICATION_NOT_FOUND`: no notification with this id in this workspace. |
715
744
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
716
745
 
@@ -733,12 +762,13 @@ Cancels every live notification sent with this `cancellation_key`: deliveries st
733
762
 
734
763
  | Status | Error class | Codes | When |
735
764
  |---|---|---|---|
736
- | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `cancellation_key` is missing. |
737
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
765
+ | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `cancellation_key` is missing or not 1-255 characters of `A-Z a-z 0-9 . _ : @ \| -`. |
766
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
767
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
738
768
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
739
769
 
740
770
  ```ts
741
- const cancelByKey = await notify.notifications.cancelByKey({ cancellation_key: "invite:inv_77" });
771
+ const cancelByKey = await notify.notifications.cancelByKey({ cancellation_key: "invite.sent:inv_77" });
742
772
  ```
743
773
 
744
774
  [HTTP reference](https://productcraft.co/docs/notify/api-reference#post-v1-workspaces-workspace-id-notifications-cancel)
@@ -758,7 +788,8 @@ Newest first. Filter by `type`, `tag` (`key:value` or `key`), `tenant` or `cance
758
788
  | Status | Error class | Codes | When |
759
789
  |---|---|---|---|
760
790
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR` on a bad filter, or `BAD_REQUEST`: invalid cursor. |
761
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
791
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
792
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
762
793
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
763
794
 
764
795
  ```ts
@@ -782,7 +813,8 @@ Archives the notification's inbox items for every recipient (for example once an
782
813
 
783
814
  | Status | Error class | Codes | When |
784
815
  |---|---|---|---|
785
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
816
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
817
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
786
818
  | 404 | `NotFoundError` | `NOT_FOUND`, `NOTIFICATION_NOT_FOUND` | `NOTIFICATION_NOT_FOUND`: no notification with this id in this workspace. |
787
819
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
788
820
 
@@ -804,7 +836,8 @@ With its data and the number of deliveries per channel and state.
804
836
 
805
837
  | Status | Error class | Codes | When |
806
838
  |---|---|---|---|
807
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
839
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
840
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
808
841
  | 404 | `NotFoundError` | `NOT_FOUND`, `NOTIFICATION_NOT_FOUND` | `NOTIFICATION_NOT_FOUND`: no notification with this id in this workspace. |
809
842
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
810
843
 
@@ -820,7 +853,7 @@ const notification = await notify.notifications.retrieve("0193a5f2-7c1e-7b3a-9f1
820
853
 
821
854
  Send a notification.
822
855
 
823
- Notifies up to 1,000 recipients with one notification type, across the type's channels (in-app inbox, email, push, web push), honouring each recipient's preferences. Returns 202 as soon as the send is stored; delivery happens in the background (see `GET /deliveries`). Unknown external ids do not fail the call: they are listed in `skipped` (`create_missing: true` creates them instead); the call fails only when no recipient can be notified. An `Idempotency-Key` is **required** (a deterministic one such as `invoice.paid:inv_123` is best): the same key and body return the same notification, even when retried much later; the same key with a different body is a 409. `dry_run: true` returns the plan per recipient and channel with the reason for every skip, and stores nothing (200, no key needed). Limits: 3,000 recipients per minute per workspace; 30 notifications per minute per recipient (critical types have a separate 30), beyond which deliveries are skipped as `rate_limited`.
856
+ Notifies up to 1,000 recipients with one notification type, across the type's channels (in-app inbox, email, push, web push), honouring each recipient's preferences. Returns 202 as soon as the send is stored; delivery happens in the background (see `GET /deliveries`). Unknown external ids do not fail the call: they are listed in `skipped` (`create_missing: true` creates them instead); the call fails only when no recipient can be notified. An `Idempotency-Key` is **required** (a deterministic one built from your event, such as `invoice.paid:inv_123`, is best; dots are fine): the same key and body return the same notification, even when retried much later; the same key with a different body is a 409. `dry_run: true` returns the plan per recipient and channel with the reason for every skip, and stores nothing (200, no key needed). Limits: 3,000 recipients per minute per workspace; 30 notifications per minute per recipient (critical types have a separate 30), beyond which deliveries are skipped as `rate_limited`.
824
857
 
825
858
  - Params: `Notify.NotificationSendParams`
826
859
  - Idempotent: an `Idempotency-Key` is sent automatically and reused on retries
@@ -828,8 +861,9 @@ Notifies up to 1,000 recipients with one notification type, across the type's ch
828
861
 
829
862
  | Status | Error class | Codes | When |
830
863
  |---|---|---|---|
831
- | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `IDEMPOTENCY_KEY_REQUIRED`, `TOO_MANY_RECIPIENTS` | `IDEMPOTENCY_KEY_REQUIRED`: no `Idempotency-Key`; `TOO_MANY_RECIPIENTS`: over 1,000; `VALIDATION_ERROR`: a field is invalid. |
832
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
864
+ | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `IDEMPOTENCY_KEY_REQUIRED`, `TOO_MANY_RECIPIENTS` | `IDEMPOTENCY_KEY_REQUIRED`: no `Idempotency-Key`; `BAD_REQUEST`: the `Idempotency-Key` is over 256 characters or has a character outside `A-Z a-z 0-9 . _ : -` (the message names it); `TOO_MANY_RECIPIENTS`: over 1,000; `VALIDATION_ERROR`: a field is invalid (an invalid `cancellation_key` included). |
865
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
866
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
833
867
  | 404 | `NotFoundError` | `NOT_FOUND`, `NOTIFICATION_TYPE_NOT_FOUND` | `NOTIFICATION_TYPE_NOT_FOUND`: no type with this key. |
834
868
  | 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the key was used with a different body. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
835
869
  | 413 | `APIError` | `PAYLOAD_TOO_LARGE`, `DATA_TOO_LARGE` | `DATA_TOO_LARGE`: `data` is over 16 KB. |
@@ -861,7 +895,8 @@ Returns a short-lived token (default 1 hour, at most 24 hours) that lets one rec
861
895
  | Status | Error class | Codes | When |
862
896
  |---|---|---|---|
863
897
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid (`errors` names it). |
864
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
898
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
899
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
865
900
  | 409 | `ConflictError` | `CONFLICT`, `RECIPIENT_ERASED` | `RECIPIENT_ERASED`: the recipient was erased in the last 24 hours (its linked Auth user was deleted). |
866
901
  | 429 | `RateLimitError` | `RATE_LIMITED` | `RATE_LIMITED`: over the mint limit; `Retry-After` gives the seconds to wait. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
867
902
 
@@ -888,7 +923,8 @@ Upserts each row like `PUT /recipients/{external_id}`, with its devices. Rows ar
888
923
  | Status | Error class | Codes | When |
889
924
  |---|---|---|---|
890
925
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `recipients` is missing, empty or longer than 1,000. |
891
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
926
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
927
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
892
928
  | 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different body. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
893
929
  | 429 | `RateLimitError` | `RATE_LIMITED` | `RATE_LIMITED`: more than 20 bulk calls in a minute; see `Retry-After`. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
894
930
 
@@ -910,7 +946,8 @@ Deletes the recipient and everything Notify holds for it: devices now, and prefe
910
946
 
911
947
  | Status | Error class | Codes | When |
912
948
  |---|---|---|---|
913
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
949
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
950
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
914
951
  | 404 | `NotFoundError` | `NOT_FOUND`, `RECIPIENT_NOT_FOUND` | `RECIPIENT_NOT_FOUND`: no recipient with this external id in this workspace. |
915
952
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
916
953
 
@@ -934,7 +971,8 @@ Creates the recipient with this external id, or updates it. Fields you leave out
934
971
  | Status | Error class | Codes | When |
935
972
  |---|---|---|---|
936
973
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid (`errors` names it). |
937
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
974
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
975
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
938
976
  | 409 | `ConflictError` | `CONFLICT`, `AUTH_USER_ALREADY_LINKED` | `AUTH_USER_ALREADY_LINKED`: the Auth end user is linked to another recipient of the workspace. |
939
977
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
940
978
 
@@ -959,7 +997,8 @@ Newest first. Filter by `email` (case-insensitive), `auth_user_id`, or `updated_
959
997
  | Status | Error class | Codes | When |
960
998
  |---|---|---|---|
961
999
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR` on a bad filter, or `BAD_REQUEST`: invalid cursor. |
962
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
1000
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
1001
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
963
1002
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
964
1003
 
965
1004
  ```ts
@@ -983,7 +1022,8 @@ The profile; devices are under `…/devices`.
983
1022
 
984
1023
  | Status | Error class | Codes | When |
985
1024
  |---|---|---|---|
986
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
1025
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
1026
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
987
1027
  | 404 | `NotFoundError` | `NOT_FOUND`, `RECIPIENT_NOT_FOUND` | `RECIPIENT_NOT_FOUND`: no recipient with this external id in this workspace. |
988
1028
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
989
1029
 
@@ -1005,7 +1045,8 @@ Every recipient token minted for this recipient so far stops working on its next
1005
1045
 
1006
1046
  | Status | Error class | Codes | When |
1007
1047
  |---|---|---|---|
1008
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
1048
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
1049
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1009
1050
  | 404 | `NotFoundError` | `NOT_FOUND`, `RECIPIENT_NOT_FOUND` | `RECIPIENT_NOT_FOUND`: no recipient with this external id in this workspace. |
1010
1051
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1011
1052
 
@@ -1030,7 +1071,8 @@ Every delivery to this recipient across notifications, newest first, with the re
1030
1071
  | Status | Error class | Codes | When |
1031
1072
  |---|---|---|---|
1032
1073
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `BAD_REQUEST`: invalid cursor. |
1033
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
1074
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
1075
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1034
1076
  | 404 | `NotFoundError` | `NOT_FOUND`, `RECIPIENT_NOT_FOUND` | `RECIPIENT_NOT_FOUND`: no recipient with this external id in this workspace. |
1035
1077
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1036
1078
 
@@ -1057,7 +1099,8 @@ Changes the fields you send on an existing recipient (404 when there is none; us
1057
1099
  | Status | Error class | Codes | When |
1058
1100
  |---|---|---|---|
1059
1101
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid (`errors` names it). |
1060
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
1102
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
1103
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1061
1104
  | 404 | `NotFoundError` | `NOT_FOUND`, `RECIPIENT_NOT_FOUND` | `RECIPIENT_NOT_FOUND`: no recipient with this external id in this workspace. |
1062
1105
  | 409 | `ConflictError` | `CONFLICT`, `AUTH_USER_ALREADY_LINKED` | `AUTH_USER_ALREADY_LINKED`: the Auth end user is linked to another recipient of the workspace. |
1063
1106
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
@@ -1085,7 +1128,8 @@ Registers an APNs or FCM token, or a browser web push subscription, for the reci
1085
1128
  | Status | Error class | Codes | When |
1086
1129
  |---|---|---|---|
1087
1130
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid (`errors` names it). |
1088
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
1131
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
1132
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1089
1133
  | 404 | `NotFoundError` | `NOT_FOUND`, `RECIPIENT_NOT_FOUND` | `RECIPIENT_NOT_FOUND`: no recipient with this external id; create it with `PUT` first. |
1090
1134
  | 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `IDEMPOTENCY_KEY_REUSE`: the `Idempotency-Key` was already used with a different body. Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
1091
1135
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `DEVICE_TOKEN_INVALID`, `WEBPUSH_ENDPOINT_NOT_ALLOWED` | `DEVICE_TOKEN_INVALID`: the token or subscription is malformed for its channel (or `environment` is missing for APNs); `WEBPUSH_ENDPOINT_NOT_ALLOWED`: the endpoint is not https on a known push service, or resolves to a private address. |
@@ -1109,7 +1153,8 @@ Deletes the device (call it when the user signs out on that device). Pushes stop
1109
1153
 
1110
1154
  | Status | Error class | Codes | When |
1111
1155
  |---|---|---|---|
1112
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
1156
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
1157
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1113
1158
  | 404 | `NotFoundError` | `NOT_FOUND`, `RECIPIENT_NOT_FOUND`, `DEVICE_NOT_FOUND` | `RECIPIENT_NOT_FOUND`, or `DEVICE_NOT_FOUND`: the recipient has no device with this id. |
1114
1159
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1115
1160
 
@@ -1131,7 +1176,8 @@ Most recently seen first: the active ones (at most 20) and any invalid or pruned
1131
1176
 
1132
1177
  | Status | Error class | Codes | When |
1133
1178
  |---|---|---|---|
1134
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
1179
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
1180
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1135
1181
  | 404 | `NotFoundError` | `NOT_FOUND`, `RECIPIENT_NOT_FOUND` | `RECIPIENT_NOT_FOUND`: no recipient with this external id in this workspace. |
1136
1182
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1137
1183
 
@@ -1158,7 +1204,8 @@ What the recipient sees in their in-app inbox, newest first, with their unseen a
1158
1204
  | Status | Error class | Codes | When |
1159
1205
  |---|---|---|---|
1160
1206
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR` on a bad filter, or `BAD_REQUEST`: invalid cursor. |
1161
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
1207
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
1208
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1162
1209
  | 404 | `NotFoundError` | `NOT_FOUND`, `RECIPIENT_NOT_FOUND` | `RECIPIENT_NOT_FOUND`: no recipient with this external id in this workspace. |
1163
1210
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1164
1211
 
@@ -1187,7 +1234,8 @@ Sets the complete set of cells: cells you leave out are removed. Most specific w
1187
1234
  | Status | Error class | Codes | When |
1188
1235
  |---|---|---|---|
1189
1236
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a cell is malformed or repeated. |
1190
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
1237
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
1238
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1191
1239
  | 404 | `NotFoundError` | `NOT_FOUND`, `RECIPIENT_NOT_FOUND` | `RECIPIENT_NOT_FOUND`: no recipient with this external id in this workspace. |
1192
1240
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `CATEGORY_NOT_FOUND`, `NOTIFICATION_TYPE_NOT_FOUND`, `PREFERENCE_LOCKED` | `CATEGORY_NOT_FOUND` / `NOTIFICATION_TYPE_NOT_FOUND`: a cell names an unknown key; `PREFERENCE_LOCKED`: the channel is mandatory for that category and cannot be turned off. |
1193
1241
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
@@ -1210,7 +1258,8 @@ The cells the recipient set, unsubscribe-all, time zone and quiet hours. Anythin
1210
1258
 
1211
1259
  | Status | Error class | Codes | When |
1212
1260
  |---|---|---|---|
1213
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
1261
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
1262
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1214
1263
  | 404 | `NotFoundError` | `NOT_FOUND`, `RECIPIENT_NOT_FOUND` | `RECIPIENT_NOT_FOUND`: no recipient with this external id in this workspace. |
1215
1264
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1216
1265
 
@@ -1234,7 +1283,8 @@ Sets or removes (`enabled: null`) the cells you send and keeps the others; also
1234
1283
  | Status | Error class | Codes | When |
1235
1284
  |---|---|---|---|
1236
1285
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a cell is malformed or repeated. |
1237
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
1286
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
1287
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1238
1288
  | 404 | `NotFoundError` | `NOT_FOUND`, `RECIPIENT_NOT_FOUND` | `RECIPIENT_NOT_FOUND`: no recipient with this external id in this workspace. |
1239
1289
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `CATEGORY_NOT_FOUND`, `NOTIFICATION_TYPE_NOT_FOUND`, `PREFERENCE_LOCKED` | `CATEGORY_NOT_FOUND` / `NOTIFICATION_TYPE_NOT_FOUND`: a cell names an unknown key; `PREFERENCE_LOCKED`: the channel is mandatory for that category and cannot be turned off. |
1240
1290
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
@@ -1259,7 +1309,8 @@ Email on/off and, after an automatic pause, when and why email was paused; the d
1259
1309
 
1260
1310
  | Status | Error class | Codes | When |
1261
1311
  |---|---|---|---|
1262
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
1312
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
1313
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1263
1314
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1264
1315
 
1265
1316
  ```ts
@@ -1280,7 +1331,8 @@ Every recipient token of the workspace stops working on its next call (`401 RECI
1280
1331
 
1281
1332
  | Status | Error class | Codes | When |
1282
1333
  |---|---|---|---|
1283
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
1334
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
1335
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1284
1336
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1285
1337
 
1286
1338
  ```ts
@@ -1303,7 +1355,8 @@ Turn email on or off, set the default time zone and quiet hours (`null` clears e
1303
1355
  | Status | Error class | Codes | When |
1304
1356
  |---|---|---|---|
1305
1357
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid (`errors` names it). |
1306
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
1358
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
1359
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1307
1360
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1308
1361
 
1309
1362
  ```ts
@@ -1326,7 +1379,8 @@ Rows, in order: `notification_type` (not_set until an active type exists), `emai
1326
1379
 
1327
1380
  | Status | Error class | Codes | When |
1328
1381
  |---|---|---|---|
1329
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks `notify.channel.read`, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
1382
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
1383
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks `notify.channel.read`, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1330
1384
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1331
1385
 
1332
1386
  ```ts
@@ -1351,7 +1405,8 @@ Daily delivery counts per channel for a range of UTC days (default the last 30,
1351
1405
  | Status | Error class | Codes | When |
1352
1406
  |---|---|---|---|
1353
1407
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a date is invalid, `from` is after `to`, or the range is longer than 90 days. |
1354
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks `notify.message.read`, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). |
1408
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | Missing, expired, revoked or invalid bearer token (`UNAUTHORIZED`): send a workspace API key or a console session as `Authorization: Bearer <token>`. A recipient token is refused here with `RECIPIENT_TOKEN_INVALID`: it works only on the client API (`/v1/client/…`). |
1409
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks `notify.message.read`, or the workspace has not enabled Notify (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1355
1410
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1356
1411
 
1357
1412
  ```ts
@@ -1387,8 +1442,8 @@ Deliveries are signed with the Standard Webhooks headers `webhook-id`, `webhook-
1387
1442
  | Status | Error class | Codes | When |
1388
1443
  |---|---|---|---|
1389
1444
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR`, `WEBHOOK_EVENT_TYPE_UNKNOWN` | Validation failure: URL not https with a public host, or an unknown event type (`WEBHOOK_EVENT_TYPE_UNKNOWN`). |
1390
- | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
1391
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
1445
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | `UNAUTHORIZED`: Missing or invalid bearer token. A recipient token is refused with `RECIPIENT_TOKEN_INVALID` (it works only on `/v1/client/…`). |
1446
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1392
1447
  | 409 | `ConflictError` | `CONFLICT`, `WEBHOOK_ENDPOINT_LIMIT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Already 10 endpoints (`WEBHOOK_ENDPOINT_LIMIT`), or Idempotency-Key reused with a different body (`IDEMPOTENCY_KEY_REUSE`). Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
1393
1448
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY` | The URL points at a private, loopback or internal address. |
1394
1449
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
@@ -1412,8 +1467,8 @@ Queued retries are dropped. Its past attempts stay in the event log until the ev
1412
1467
  | Status | Error class | Codes | When |
1413
1468
  |---|---|---|---|
1414
1469
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `endpoint_id` is not a UUID. |
1415
- | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
1416
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
1470
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | `UNAUTHORIZED`: Missing or invalid bearer token. A recipient token is refused with `RECIPIENT_TOKEN_INVALID` (it works only on `/v1/client/…`). |
1471
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1417
1472
  | 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
1418
1473
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1419
1474
 
@@ -1437,8 +1492,8 @@ At most 10, so this is always one page. Signing secrets are never returned here,
1437
1492
  | Status | Error class | Codes | When |
1438
1493
  |---|---|---|---|
1439
1494
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | The scope id in the path is malformed. |
1440
- | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
1441
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
1495
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | `UNAUTHORIZED`: Missing or invalid bearer token. A recipient token is refused with `RECIPIENT_TOKEN_INVALID` (it works only on `/v1/client/…`). |
1496
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1442
1497
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1443
1498
 
1444
1499
  ```ts
@@ -1462,8 +1517,8 @@ The endpoint's URL, subscription, on/off state, failure streak and the last 4 ch
1462
1517
  | Status | Error class | Codes | When |
1463
1518
  |---|---|---|---|
1464
1519
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `endpoint_id` is not a UUID. |
1465
- | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
1466
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
1520
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | `UNAUTHORIZED`: Missing or invalid bearer token. A recipient token is refused with `RECIPIENT_TOKEN_INVALID` (it works only on `/v1/client/…`). |
1521
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1467
1522
  | 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
1468
1523
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1469
1524
 
@@ -1488,8 +1543,8 @@ For `grace_hours` (default 24) the previous secret keeps signing too: `webhook-s
1488
1543
  | Status | Error class | Codes | When |
1489
1544
  |---|---|---|---|
1490
1545
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `grace_hours` out of range, or `endpoint_id` is not a UUID. |
1491
- | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
1492
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
1546
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | `UNAUTHORIZED`: Missing or invalid bearer token. A recipient token is refused with `RECIPIENT_TOKEN_INVALID` (it works only on `/v1/client/…`). |
1547
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1493
1548
  | 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
1494
1549
  | 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Idempotency-Key reused with a different body (`IDEMPOTENCY_KEY_REUSE`). Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
1495
1550
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
@@ -1515,8 +1570,8 @@ Delivers the catalogue example of `event_type`, signed like any delivery, with `
1515
1570
  | Status | Error class | Codes | When |
1516
1571
  |---|---|---|---|
1517
1572
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Unknown `event_type`, or `endpoint_id` is not a UUID. |
1518
- | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
1519
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
1573
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | `UNAUTHORIZED`: Missing or invalid bearer token. A recipient token is refused with `RECIPIENT_TOKEN_INVALID` (it works only on `/v1/client/…`). |
1574
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1520
1575
  | 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
1521
1576
  | 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Idempotency-Key reused with a different body (`IDEMPOTENCY_KEY_REUSE`). Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
1522
1577
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
@@ -1542,8 +1597,8 @@ Only the fields sent change. `enabled: true` (or a new URL) also clears an autom
1542
1597
  | Status | Error class | Codes | When |
1543
1598
  |---|---|---|---|
1544
1599
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Validation failure, or `endpoint_id` is not a UUID. |
1545
- | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
1546
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
1600
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | `UNAUTHORIZED`: Missing or invalid bearer token. A recipient token is refused with `RECIPIENT_TOKEN_INVALID` (it works only on `/v1/client/…`). |
1601
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1547
1602
  | 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
1548
1603
  | 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | Idempotency-Key reused with a different body (`IDEMPOTENCY_KEY_REUSE`). Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
1549
1604
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY` | The new URL points at a private, loopback or internal address. |
@@ -1569,8 +1624,8 @@ Each type with a plain description, its group and an example `data` object (what
1569
1624
 
1570
1625
  | Status | Error class | Codes | When |
1571
1626
  |---|---|---|---|
1572
- | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
1573
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
1627
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | `UNAUTHORIZED`: Missing or invalid bearer token. A recipient token is refused with `RECIPIENT_TOKEN_INVALID` (it works only on `/v1/client/…`). |
1628
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1574
1629
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1575
1630
 
1576
1631
  ```ts
@@ -1596,8 +1651,8 @@ Every event logged while at least one endpoint existed, with the latest state pe
1596
1651
  | Status | Error class | Codes | When |
1597
1652
  |---|---|---|---|
1598
1653
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | Invalid filter value or cursor. |
1599
- | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
1600
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
1654
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | `UNAUTHORIZED`: Missing or invalid bearer token. A recipient token is refused with `RECIPIENT_TOKEN_INVALID` (it works only on `/v1/client/…`). |
1655
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1601
1656
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1602
1657
 
1603
1658
  ```ts
@@ -1624,8 +1679,8 @@ Same body and `webhook-id`, freshly signed, to every switched-on endpoint that r
1624
1679
  | Status | Error class | Codes | When |
1625
1680
  |---|---|---|---|
1626
1681
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `event_id` is not `evt_<uuid>`, or `endpoint_id` is not a UUID. |
1627
- | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
1628
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
1682
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | `UNAUTHORIZED`: Missing or invalid bearer token. A recipient token is refused with `RECIPIENT_TOKEN_INVALID` (it works only on `/v1/client/…`). |
1683
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1629
1684
  | 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_EVENT_NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such event here (`WEBHOOK_EVENT_NOT_FOUND`); events are kept for 30 days. Or No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
1630
1685
  | 409 | `ConflictError` | `CONFLICT`, `WEBHOOK_ENDPOINT_NOT_SUBSCRIBED`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `endpoint_id` is switched off or does not receive this event type (`WEBHOOK_ENDPOINT_NOT_SUBSCRIBED`), or Idempotency-Key reused with a different body (`IDEMPOTENCY_KEY_REUSE`). Idempotency: `IDEMPOTENCY_KEY_REUSE` when this `Idempotency-Key` was already used with a different body or route; `IDEMPOTENCY_IN_PROGRESS` while another request with the same key is still running (retry after `Retry-After` seconds, with the same key). |
1631
1686
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
@@ -1649,8 +1704,8 @@ The event as it was sent (`type`, `data`) and every delivery attempt to every en
1649
1704
  | Status | Error class | Codes | When |
1650
1705
  |---|---|---|---|
1651
1706
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `event_id` is not `evt_<uuid>`. |
1652
- | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
1653
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
1707
+ | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID` | `UNAUTHORIZED`: Missing or invalid bearer token. A recipient token is refused with `RECIPIENT_TOKEN_INVALID` (it works only on `/v1/client/…`). |
1708
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `notify.webhook.read` (reads) or `notify.webhook.manage` (changes, Send test, replay), or Notify is not enabled for the workspace (`SERVICE_NOT_ENABLED`). Also `FORBIDDEN` when the credential belongs to another workspace than the URL names, or the URL uses the workspace slug instead of its id (a UUID). |
1654
1709
  | 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_EVENT_NOT_FOUND` | No such event here (`WEBHOOK_EVENT_NOT_FOUND`); events are kept for 30 days. |
1655
1710
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1656
1711
 
@@ -1675,7 +1730,7 @@ Call it when the user signs out on the device: pushes to it stop at once.
1675
1730
  | Status | Error class | Codes | When |
1676
1731
  |---|---|---|---|
1677
1732
  | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID`, `RECIPIENT_TOKEN_EXPIRED` | `RECIPIENT_TOKEN_INVALID`: no recipient token, a malformed or forged one, an API key, or a revoked token (mint a new one); `RECIPIENT_TOKEN_EXPIRED`: the token expired (mint a new one). |
1678
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `devices:write` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins. |
1733
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED`, `SERVICE_NOT_ENABLED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `devices:write` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins; `SERVICE_NOT_ENABLED`: Notify is turned off for the workspace. |
1679
1734
  | 404 | `NotFoundError` | `NOT_FOUND`, `DEVICE_NOT_FOUND` | `DEVICE_NOT_FOUND`: the recipient has no device with this id. |
1680
1735
  | 429 | `RateLimitError` | `RATE_LIMITED` | `RATE_LIMITED`: over 60 client calls per minute for this recipient; `Retry-After` gives the seconds to wait. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1681
1736
 
@@ -1700,7 +1755,7 @@ Registers the app's APNs or FCM token, or the browser's web push subscription, f
1700
1755
  |---|---|---|---|
1701
1756
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid (`errors` names it). |
1702
1757
  | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID`, `RECIPIENT_TOKEN_EXPIRED` | `RECIPIENT_TOKEN_INVALID`: no recipient token, a malformed or forged one, an API key, or a revoked token (mint a new one); `RECIPIENT_TOKEN_EXPIRED`: the token expired (mint a new one). |
1703
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `devices:write` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins. |
1758
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED`, `SERVICE_NOT_ENABLED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `devices:write` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins; `SERVICE_NOT_ENABLED`: Notify is turned off for the workspace. |
1704
1759
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `DEVICE_TOKEN_INVALID`, `WEBPUSH_ENDPOINT_NOT_ALLOWED` | `DEVICE_TOKEN_INVALID`: the token or subscription is malformed for its channel (or `environment` is missing for APNs); `WEBPUSH_ENDPOINT_NOT_ALLOWED`: the endpoint is not https on a known push service. |
1705
1760
  | 429 | `RateLimitError` | `RATE_LIMITED` | `RATE_LIMITED`: over 60 client calls per minute for this recipient; `Retry-After` gives the seconds to wait. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1706
1761
 
@@ -1725,7 +1780,7 @@ Unseen and unread counts for the badge, cheap enough to poll every 30 seconds or
1725
1780
  | Status | Error class | Codes | When |
1726
1781
  |---|---|---|---|
1727
1782
  | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID`, `RECIPIENT_TOKEN_EXPIRED` | `RECIPIENT_TOKEN_INVALID`: no recipient token, a malformed or forged one, an API key, or a revoked token (mint a new one); `RECIPIENT_TOKEN_EXPIRED`: the token expired (mint a new one). |
1728
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `inbox:read` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins. |
1783
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED`, `SERVICE_NOT_ENABLED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `inbox:read` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins; `SERVICE_NOT_ENABLED`: Notify is turned off for the workspace. |
1729
1784
  | 429 | `RateLimitError` | `RATE_LIMITED` | `RATE_LIMITED`: over 60 client calls per minute for this recipient; `Retry-After` gives the seconds to wait. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1730
1785
 
1731
1786
  ```ts
@@ -1748,7 +1803,7 @@ Call it when the recipient presses the item or one of its buttons (`action_key`)
1748
1803
  | Status | Error class | Codes | When |
1749
1804
  |---|---|---|---|
1750
1805
  | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID`, `RECIPIENT_TOKEN_EXPIRED` | `RECIPIENT_TOKEN_INVALID`: no recipient token, a malformed or forged one, an API key, or a revoked token (mint a new one); `RECIPIENT_TOKEN_EXPIRED`: the token expired (mint a new one). |
1751
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `inbox:write` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins. |
1806
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED`, `SERVICE_NOT_ENABLED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `inbox:write` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins; `SERVICE_NOT_ENABLED`: Notify is turned off for the workspace. |
1752
1807
  | 404 | `NotFoundError` | `NOT_FOUND`, `INBOX_ITEM_NOT_FOUND` | `INBOX_ITEM_NOT_FOUND`: the recipient has no item with this id (or it was retracted). |
1753
1808
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: the item has no button with this `action_key`. |
1754
1809
  | 429 | `RateLimitError` | `RATE_LIMITED` | `RATE_LIMITED`: over 60 client calls per minute for this recipient; `Retry-After` gives the seconds to wait. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
@@ -1775,7 +1830,7 @@ The recipient's in-app inbox, newest first, with the unseen and unread counts fo
1775
1830
  |---|---|---|---|
1776
1831
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a query parameter is invalid, or the cursor is not one this route returned. |
1777
1832
  | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID`, `RECIPIENT_TOKEN_EXPIRED` | `RECIPIENT_TOKEN_INVALID`: no recipient token, a malformed or forged one, an API key, or a revoked token (mint a new one); `RECIPIENT_TOKEN_EXPIRED`: the token expired (mint a new one). |
1778
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `inbox:read` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins. |
1833
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED`, `SERVICE_NOT_ENABLED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `inbox:read` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins; `SERVICE_NOT_ENABLED`: Notify is turned off for the workspace. |
1779
1834
  | 429 | `RateLimitError` | `RATE_LIMITED` | `RATE_LIMITED`: over 60 client calls per minute for this recipient; `Retry-After` gives the seconds to wait. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1780
1835
 
1781
1836
  ```ts
@@ -1802,7 +1857,7 @@ Marks up to 100 items (`ids`), or every item up to and including `before_id` ("m
1802
1857
  |---|---|---|---|
1803
1858
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid, or not exactly one of `ids` and `before_id` was given. |
1804
1859
  | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID`, `RECIPIENT_TOKEN_EXPIRED` | `RECIPIENT_TOKEN_INVALID`: no recipient token, a malformed or forged one, an API key, or a revoked token (mint a new one); `RECIPIENT_TOKEN_EXPIRED`: the token expired (mint a new one). |
1805
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `inbox:write` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins. |
1860
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED`, `SERVICE_NOT_ENABLED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `inbox:write` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins; `SERVICE_NOT_ENABLED`: Notify is turned off for the workspace. |
1806
1861
  | 429 | `RateLimitError` | `RATE_LIMITED` | `RATE_LIMITED`: over 60 client calls per minute for this recipient; `Retry-After` gives the seconds to wait. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1807
1862
 
1808
1863
  ```ts
@@ -1826,7 +1881,7 @@ The workspace's categories with their per-channel defaults (`mandatory` channels
1826
1881
  | Status | Error class | Codes | When |
1827
1882
  |---|---|---|---|
1828
1883
  | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID`, `RECIPIENT_TOKEN_EXPIRED` | `RECIPIENT_TOKEN_INVALID`: no recipient token, a malformed or forged one, an API key, or a revoked token (mint a new one); `RECIPIENT_TOKEN_EXPIRED`: the token expired (mint a new one). |
1829
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `preferences:read` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins. |
1884
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED`, `SERVICE_NOT_ENABLED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `preferences:read` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins; `SERVICE_NOT_ENABLED`: Notify is turned off for the workspace. |
1830
1885
  | 429 | `RateLimitError` | `RATE_LIMITED` | `RATE_LIMITED`: over 60 client calls per minute for this recipient; `Retry-After` gives the seconds to wait. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1831
1886
 
1832
1887
  ```ts
@@ -1850,7 +1905,7 @@ Sets or (with `enabled: null`) removes individual cells, and the time zone, quie
1850
1905
  |---|---|---|---|
1851
1906
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid (`errors` names it). |
1852
1907
  | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID`, `RECIPIENT_TOKEN_EXPIRED` | `RECIPIENT_TOKEN_INVALID`: no recipient token, a malformed or forged one, an API key, or a revoked token (mint a new one); `RECIPIENT_TOKEN_EXPIRED`: the token expired (mint a new one). |
1853
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `preferences:write` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins. |
1908
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED`, `SERVICE_NOT_ENABLED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `preferences:write` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins; `SERVICE_NOT_ENABLED`: Notify is turned off for the workspace. |
1854
1909
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `PREFERENCE_LOCKED`, `CATEGORY_NOT_FOUND`, `NOTIFICATION_TYPE_NOT_FOUND` | `PREFERENCE_LOCKED`: the channel is mandatory for the category; `CATEGORY_NOT_FOUND` / `NOTIFICATION_TYPE_NOT_FOUND`: no category or type with that key. |
1855
1910
  | 429 | `RateLimitError` | `RATE_LIMITED` | `RATE_LIMITED`: over 60 client calls per minute for this recipient; `Retry-After` gives the seconds to wait. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1856
1911
 
@@ -1875,7 +1930,7 @@ The VAPID public key the browser subscribes with (`pushManager.subscribe({ appli
1875
1930
  | Status | Error class | Codes | When |
1876
1931
  |---|---|---|---|
1877
1932
  | 401 | `AuthenticationError` | `UNAUTHORIZED`, `RECIPIENT_TOKEN_INVALID`, `RECIPIENT_TOKEN_EXPIRED` | `RECIPIENT_TOKEN_INVALID`: no recipient token, a malformed or forged one, an API key, or a revoked token (mint a new one); `RECIPIENT_TOKEN_EXPIRED`: the token expired (mint a new one). |
1878
- | 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `devices:write` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins. |
1933
+ | 403 | `PermissionDeniedError` | `FORBIDDEN`, `RECIPIENT_TOKEN_SCOPE`, `ORIGIN_NOT_ALLOWED`, `SERVICE_NOT_ENABLED` | `RECIPIENT_TOKEN_SCOPE`: the token lacks the `devices:write` scope; `ORIGIN_NOT_ALLOWED`: the browser origin is not in the workspace client origins; `SERVICE_NOT_ENABLED`: Notify is turned off for the workspace. |
1879
1934
  | 404 | `NotFoundError` | `NOT_FOUND`, `CHANNEL_NOT_CONFIGURED` | `CHANNEL_NOT_CONFIGURED`: the workspace has no web push key yet (generate one in the console or with `POST /channels/webpush/vapid-keys`). |
1880
1935
  | 429 | `RateLimitError` | `RATE_LIMITED` | `RATE_LIMITED`: over 60 client calls per minute for this recipient; `Retry-After` gives the seconds to wait. Per-IP limit: more than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1881
1936
 
@@ -1951,7 +2006,6 @@ A recipient token minted by your backend with `POST /v1/workspaces/{workspace_id
1951
2006
  | `CREDENTIAL_MISMATCH` | The credential belongs to a different app (bundle id or Firebase project id differs). |
1952
2007
  | `DEVICE_TOKEN_INVALID` | The device token or web push subscription is malformed for its platform. |
1953
2008
  | `WEBPUSH_ENDPOINT_NOT_ALLOWED` | The web push subscription endpoint is not a known push service. |
1954
- | `MAIL_NOT_ENABLED` | The email channel needs the Mail product enabled with a verified sender. |
1955
2009
  | `RECIPIENT_TOKEN_INVALID` | The recipient token is malformed, has a bad signature or was revoked. |
1956
2010
  | `RECIPIENT_TOKEN_EXPIRED` | The recipient token has expired; mint a new one from your backend. |
1957
2011
  | `RECIPIENT_TOKEN_SCOPE` | The recipient token does not allow this operation. |
@@ -1959,8 +2013,6 @@ A recipient token minted by your backend with `POST /v1/workspaces/{workspace_id
1959
2013
  | `STREAM_LIMIT` | The recipient has the maximum number of open real-time streams. |
1960
2014
  | `LIMIT_EXCEEDED` | A preview limit of the workspace was reached. |
1961
2015
  | `SEND_AT_OUT_OF_RANGE` | `send_at` or `delay_seconds` is in the past or beyond the type TTL. |
1962
- | `EMAIL_PAUSED` | Email sending is paused for this workspace. |
1963
- | `EMAIL_BACKLOG_FULL` | The workspace email backlog is full; retry later. |
1964
2016
  | `UNSAFE_URL` | A URL field does not use https (http is accepted only for localhost). |
1965
2017
  | `AUTH_USER_ALREADY_LINKED` | The Auth end user is already linked to another recipient in this workspace. |
1966
2018
  | `DEVICE_NOT_FOUND` | The recipient has no device with this id. |