@productcraft/flags 0.3.0 → 0.4.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.
Files changed (34) hide show
  1. package/api.md +105 -2
  2. package/dist/browser/{chunk-FXZVXQ75.cjs → chunk-CXYODDHM.cjs} +109 -6
  3. package/dist/browser/chunk-CXYODDHM.cjs.map +1 -0
  4. package/dist/browser/{chunk-4LRAE3F3.js → chunk-TCVKCN3S.js} +109 -6
  5. package/dist/browser/chunk-TCVKCN3S.js.map +1 -0
  6. package/dist/browser/index.cjs +3 -3
  7. package/dist/browser/index.js +1 -1
  8. package/dist/browser/management.cjs +2 -2
  9. package/dist/browser/management.js +1 -1
  10. package/dist/{chunk-2YRDLKNB.js → chunk-7237IZU3.js} +109 -6
  11. package/dist/chunk-7237IZU3.js.map +1 -0
  12. package/dist/{chunk-TSRLPHJ5.js → chunk-NB7OGN6R.js} +3 -3
  13. package/dist/{chunk-TSRLPHJ5.js.map → chunk-NB7OGN6R.js.map} +1 -1
  14. package/dist/{chunk-WI4EZXOV.cjs → chunk-NSAKFGTJ.cjs} +109 -6
  15. package/dist/chunk-NSAKFGTJ.cjs.map +1 -0
  16. package/dist/{chunk-QTDMUNLG.cjs → chunk-Q3P66XRI.cjs} +3 -3
  17. package/dist/{chunk-QTDMUNLG.cjs.map → chunk-Q3P66XRI.cjs.map} +1 -1
  18. package/dist/{client-bVEJfS6_.d.cts → client-BwoMpm8_.d.cts} +995 -10
  19. package/dist/{client-bVEJfS6_.d.ts → client-BwoMpm8_.d.ts} +995 -10
  20. package/dist/index.cjs +8 -8
  21. package/dist/index.d.cts +1 -1
  22. package/dist/index.d.ts +1 -1
  23. package/dist/index.js +2 -2
  24. package/dist/management.cjs +2 -2
  25. package/dist/management.d.cts +1 -1
  26. package/dist/management.d.ts +1 -1
  27. package/dist/management.js +1 -1
  28. package/dist/testing.cjs +3 -3
  29. package/dist/testing.js +1 -1
  30. package/package.json +1 -1
  31. package/dist/browser/chunk-4LRAE3F3.js.map +0 -1
  32. package/dist/browser/chunk-FXZVXQ75.cjs.map +0 -1
  33. package/dist/chunk-2YRDLKNB.js.map +0 -1
  34. package/dist/chunk-WI4EZXOV.cjs.map +0 -1
package/api.md CHANGED
@@ -17,9 +17,11 @@ One change with `before`, `after`, a JSON Patch `diff` (RFC 6902) and the summar
17
17
 
18
18
  | Status | Error class | Codes | When |
19
19
  |---|---|---|---|
20
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
20
21
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
21
22
  | 404 | `NotFoundError` | `NOT_FOUND`, `CHANGE_NOT_FOUND` | `CHANGE_NOT_FOUND`: no such change in this workspace (or it was pruned). |
22
23
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
24
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
23
25
 
24
26
  ```ts
25
27
  const changeDetail = await flags.changes.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -41,11 +43,13 @@ Writes the change's `before` back as a new change (`reverts_change_id` points to
41
43
  | Status | Error class | Codes | When |
42
44
  |---|---|---|---|
43
45
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `version` is missing (value and segment restores) or invalid. |
46
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
44
47
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). A restore needs the actions of the original edit too. |
45
48
  | 404 | `NotFoundError` | `NOT_FOUND`, `CHANGE_NOT_FOUND`, `SETTING_NOT_FOUND`, `SEGMENT_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `CHANGE_NOT_FOUND`; `SETTING_NOT_FOUND`, `SEGMENT_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND` when the entity was deleted since. |
46
49
  | 409 | `ConflictError` | `CONFLICT`, `VERSION_CONFLICT`, `KEY_ALREADY_EXISTS`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `VERSION_CONFLICT`: the entity changed since you read it (`details.current_version`), or the setting no longer matches this change. `KEY_ALREADY_EXISTS`: the restored key is taken. 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). |
47
50
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `REVERT_NOT_SUPPORTED`, `NOTHING_TO_RESTORE`, `INVALID_VALUE`, `INVALID_TARGETING`, `SEGMENT_NOT_FOUND`, `PREREQUISITE_NOT_FOUND`, `PREREQUISITE_TYPE_MISMATCH`, `CIRCULAR_PREREQUISITE`, `CONFIDENTIAL_LIST_NOT_EDITABLE`, `LIMIT_EXCEEDED`, `NOTE_REQUIRED`, `CONFIG_TOO_LARGE`, `OWNER_NOT_A_MEMBER` | `REVERT_NOT_SUPPORTED`: this kind of change cannot be restored. `NOTHING_TO_RESTORE`: it already matches the version before this change. The restored or copied targeting is refused by the normal write checks: `INVALID_VALUE`, `INVALID_TARGETING`, `SEGMENT_NOT_FOUND` (a segment it used was deleted), `PREREQUISITE_NOT_FOUND`, `PREREQUISITE_TYPE_MISMATCH`, `CIRCULAR_PREREQUISITE`, `CONFIDENTIAL_LIST_NOT_EDITABLE`, `LIMIT_EXCEEDED`, `NOTE_REQUIRED` (the environment requires a `note`), `CONFIG_TOO_LARGE`, or `OWNER_NOT_A_MEMBER` (a restored owner left the workspace). |
48
51
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
52
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
49
53
 
50
54
  ```ts
51
55
  const changeDetail = await flags.changes.revert("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { note: "Roll back FLAG-142" });
@@ -69,9 +73,11 @@ Each setting's value and targeting side by side in 2-5 environments, with `diffe
69
73
  | Status | Error class | Codes | When |
70
74
  |---|---|---|---|
71
75
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `environment_ids` is not 2-5 environment ids. |
76
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
72
77
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
73
78
  | 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `CONFIG_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`. |
74
79
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
80
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
75
81
 
76
82
  ```ts
77
83
  for await (const config of flags.configs.compare("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {
@@ -95,9 +101,11 @@ Deletes the config with its flags, values and SDK keys in every environment. Nee
95
101
 
96
102
  | Status | Error class | Codes | When |
97
103
  |---|---|---|---|
104
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
98
105
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
99
106
  | 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND` | `CONFIG_NOT_FOUND`: no such config in this workspace. |
100
107
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
108
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
101
109
 
102
110
  ```ts
103
111
  await flags.configs.delete("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -113,9 +121,11 @@ Get a config.
113
121
 
114
122
  | Status | Error class | Codes | When |
115
123
  |---|---|---|---|
124
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
116
125
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
117
126
  | 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND` | `CONFIG_NOT_FOUND`: no such config in this workspace. |
118
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. |
128
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
119
129
 
120
130
  ```ts
121
131
  const config = await flags.configs.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -136,10 +146,12 @@ Key, name, description or order. Only the fields you send change. Needs `flags.p
136
146
  | Status | Error class | Codes | When |
137
147
  |---|---|---|---|
138
148
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid. |
149
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
139
150
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
140
151
  | 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND` | `CONFIG_NOT_FOUND`: no such config in this workspace. |
141
152
  | 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS` | `KEY_ALREADY_EXISTS`: the project already has a config with this key. |
142
153
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
154
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
143
155
 
144
156
  ```ts
145
157
  const config = await flags.configs.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { description: "string" });
@@ -163,11 +175,13 @@ Copies value and targeting (rules, splits, split attribute) of `setting_ids`, or
163
175
  | Status | Error class | Codes | When |
164
176
  |---|---|---|---|
165
177
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: neither or both of `setting_ids` / `all_differing`, the source is the target, or a bad `versions` entry. |
178
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
166
179
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). Copies need `flags.value.update` on the environment and every setting, and `flags.protected.update` into a protected environment. |
167
180
  | 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND`, `SETTING_NOT_FOUND` | `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` (target or source is not of this project) or `SETTING_NOT_FOUND`. |
168
181
  | 409 | `ConflictError` | `CONFLICT`, `VERSION_CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `VERSION_CONFLICT`: a setting changed in the target since you read it, or has no entry in `versions` (`details.conflicts[]`: `setting_id`, `key`, `current_version`, `sent_version`); nothing was copied. 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). |
169
182
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `INVALID_VALUE`, `INVALID_TARGETING`, `SEGMENT_NOT_FOUND`, `PREREQUISITE_NOT_FOUND`, `PREREQUISITE_TYPE_MISMATCH`, `CIRCULAR_PREREQUISITE`, `CONFIDENTIAL_LIST_NOT_EDITABLE`, `LIMIT_EXCEEDED`, `NOTE_REQUIRED`, `CONFIG_TOO_LARGE`, `OWNER_NOT_A_MEMBER` | The restored or copied targeting is refused by the normal write checks: `INVALID_VALUE`, `INVALID_TARGETING`, `SEGMENT_NOT_FOUND` (a segment it used was deleted), `PREREQUISITE_NOT_FOUND`, `PREREQUISITE_TYPE_MISMATCH`, `CIRCULAR_PREREQUISITE`, `CONFIDENTIAL_LIST_NOT_EDITABLE`, `LIMIT_EXCEEDED`, `NOTE_REQUIRED` (the environment requires a `note`), `CONFIG_TOO_LARGE`, or `OWNER_NOT_A_MEMBER` (a restored owner left the workspace). |
170
183
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
184
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
171
185
 
172
186
  ```ts
173
187
  const copyEnvironment = await flags.configs.environments.copy("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {
@@ -191,10 +205,12 @@ Evaluates a sample user against the published config of this environment (the cu
191
205
  | Status | Error class | Codes | When |
192
206
  |---|---|---|---|
193
207
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `user` is not an object or null, it has more than 200 attributes, more than 200 `keys`, or a bad `revision`. |
208
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
194
209
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
195
210
  | 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND`, `REVISION_NOT_FOUND` | `CONFIG_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`: no such config in this workspace, or the environment is not one of its project. `REVISION_NOT_FOUND`: the requested revision was pruned or never published. |
196
211
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `EVALUATION_BUDGET_EXCEEDED`, `INVALID_TARGETING` | `EVALUATION_BUDGET_EXCEEDED`: the evaluation ran over 250 ms; ask for fewer keys. `INVALID_TARGETING`: the stored revision is not a config the engine accepts. |
197
212
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
213
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
198
214
 
199
215
  ```ts
200
216
  const testEvaluation = await flags.configs.environments.evaluate("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { keys: ["new_checkout", "banner_text"] });
@@ -218,9 +234,11 @@ Published revisions of the config in one environment, newest first. Every write
218
234
  | Status | Error class | Codes | When |
219
235
  |---|---|---|---|
220
236
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a bad cursor or `limit`. |
237
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
221
238
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
222
239
  | 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `CONFIG_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`: no such config in this workspace, or the environment is not one of its project. |
223
240
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
241
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
224
242
 
225
243
  ```ts
226
244
  for await (const revision of flags.configs.environments.revisions.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f")) {
@@ -242,9 +260,11 @@ The config JSON (schema 1) of one revision, byte for byte what SDKs download: ke
242
260
  | Status | Error class | Codes | When |
243
261
  |---|---|---|---|
244
262
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `revision` is not a positive integer. |
263
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
245
264
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
246
265
  | 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND`, `REVISION_NOT_FOUND` | `CONFIG_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`: no such config in this workspace, or the environment is not one of its project. `REVISION_NOT_FOUND`: no such revision (never published, or pruned). |
247
266
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
267
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
248
268
 
249
269
  ```ts
250
270
  const result = await flags.configs.environments.revisions.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "1");
@@ -264,9 +284,11 @@ Revokes the secondary key now instead of at its `expires_at`. SDK servers still
264
284
 
265
285
  | Status | Error class | Codes | When |
266
286
  |---|---|---|---|
287
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
267
288
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
268
289
  | 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND`, `SDK_KEY_NOT_FOUND` | `CONFIG_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`: no such config in this workspace, or the environment is not one of its project. `SDK_KEY_NOT_FOUND`: there is no secondary key. |
269
290
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
291
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
270
292
 
271
293
  ```ts
272
294
  const sdkKeyList = await flags.configs.environments.sdkKeys.endGracePeriod("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -284,9 +306,11 @@ The SDK keys of this config in this environment, masked (prefix and last four ch
284
306
 
285
307
  | Status | Error class | Codes | When |
286
308
  |---|---|---|---|
309
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
287
310
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
288
311
  | 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `CONFIG_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`: no such config in this workspace, or the environment is not one of its project. |
289
312
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
313
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
290
314
 
291
315
  ```ts
292
316
  const sdkKeyList = await flags.configs.environments.sdkKeys.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -304,9 +328,11 @@ The full primary key, and the secondary key while a grace period runs. Needs `fl
304
328
 
305
329
  | Status | Error class | Codes | When |
306
330
  |---|---|---|---|
331
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
307
332
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
308
333
  | 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `CONFIG_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`: no such config in this workspace, or the environment is not one of its project. |
309
334
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
335
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
310
336
 
311
337
  ```ts
312
338
  const revealedSdkKeyList = await flags.configs.environments.sdkKeys.reveal("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -328,10 +354,12 @@ Mints a new primary key. The current primary becomes the secondary key and keeps
328
354
  | Status | Error class | Codes | When |
329
355
  |---|---|---|---|
330
356
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `grace_hours` is not an integer from 0 to 168, or `note` is too long. |
357
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
331
358
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
332
359
  | 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `CONFIG_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`: no such config in this workspace, or the environment is not one of its project. |
333
360
  | 409 | `ConflictError` | `CONFLICT`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | 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). |
334
361
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
362
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
335
363
 
336
364
  ```ts
337
365
  const sdkKeyList = await flags.configs.environments.sdkKeys.rotate("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { grace_hours: 24 });
@@ -355,9 +383,11 @@ Every setting of the config with its value and targeting in one environment (the
355
383
  | Status | Error class | Codes | When |
356
384
  |---|---|---|---|
357
385
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a bad cursor, `limit` or `include`. |
386
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
358
387
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
359
388
  | 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `CONFIG_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND` (not an environment of the config's project). |
360
389
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
390
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
361
391
 
362
392
  ```ts
363
393
  for await (const value of flags.configs.environments.values.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f")) {
@@ -384,12 +414,13 @@ Adds a feature flag (`boolean`) or a typed setting to the config, with a value i
384
414
  | Status | Error class | Codes | When |
385
415
  |---|---|---|---|
386
416
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is missing or invalid. |
417
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
387
418
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
388
419
  | 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND` | `CONFIG_NOT_FOUND`: no such config in this workspace. |
389
420
  | 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `KEY_ALREADY_EXISTS`: the config already has a setting with this key. 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). |
390
421
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `INVALID_VALUE`, `LIMIT_EXCEEDED`, `OWNER_NOT_A_MEMBER`, `NOTE_REQUIRED`, `CONFIG_TOO_LARGE` | `INVALID_VALUE`: `initial_value` does not match the type; `LIMIT_EXCEEDED`: the config has the maximum number of settings; `OWNER_NOT_A_MEMBER`: `owner_id` is not a workspace member; `NOTE_REQUIRED`. Publishing: `CONFIG_TOO_LARGE` (the rendered config would exceed 1 MiB; `details.size_bytes`, `max_bytes`) or `LIMIT_EXCEEDED` with `details.limit: comparison_values_per_config` (over 20,000 comparison values in the config); the write is not applied. |
391
422
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
392
- | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE` | `SERVICE_UNAVAILABLE`: the member lookup for `owner_id` is unavailable; retry. |
423
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | `SERVICE_UNAVAILABLE`: the member lookup for `owner_id` is unavailable; retry. Or `MANAGEMENT_UNAVAILABLE`: the whole management API is temporarily unavailable, for example while its database is unreachable; wait `Retry-After` seconds and retry. |
393
424
 
394
425
  ```ts
395
426
  const settingDetail = await flags.configs.settings.create("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { key: "new_checkout", type: "boolean" });
@@ -411,9 +442,11 @@ The config's feature flags and settings, in `ordinal` order, with filters.
411
442
  | Status | Error class | Codes | When |
412
443
  |---|---|---|---|
413
444
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a bad filter, cursor or `limit`. |
445
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
414
446
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
415
447
  | 404 | `NotFoundError` | `NOT_FOUND`, `CONFIG_NOT_FOUND` | `CONFIG_NOT_FOUND`: no such config in this workspace. |
416
448
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
449
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
417
450
 
418
451
  ```ts
419
452
  for await (const settings of flags.configs.settings.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f")) {
@@ -439,12 +472,14 @@ Reads a ConfigCat product through ConfigCat's Public Management API with credent
439
472
  | Status | Error class | Codes | When |
440
473
  |---|---|---|---|
441
474
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is missing or invalid (`source` must be `configcat`, `configcat_product_id` a uuid). |
475
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
442
476
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
443
477
  | 404 | `NotFoundError` | `NOT_FOUND`, `IMPORT_SOURCE_NOT_FOUND` | `IMPORT_SOURCE_NOT_FOUND`: the ConfigCat product does not exist, or the credentials cannot see it. |
444
478
  | 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS` | `KEY_ALREADY_EXISTS`: a project with the target name already exists (pass `target_project_name`). |
445
479
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `IMPORT_CREDENTIALS_INVALID`, `IMPORT_UNSUPPORTED`, `IMPORT_EXCEEDS_LIMITS` | `IMPORT_CREDENTIALS_INVALID`: ConfigCat rejected the credentials. `IMPORT_UNSUPPORTED`: a real run while the report lists unsupported items (`details.items`); send `skip_unsupported: true` to import without them. `IMPORT_EXCEEDS_LIMITS`: the product is larger than the Flags limits, or reading it ran over the 120 s budget (`details`: `limit`, `max`, `current`). Nothing was imported. |
446
480
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
447
481
  | 502 | `InternalServerError` | `BAD_GATEWAY`, `IMPORT_SOURCE_UNAVAILABLE` | `IMPORT_SOURCE_UNAVAILABLE`: ConfigCat answered 5xx, timed out or could not be reached. |
482
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
448
483
 
449
484
  ```ts
450
485
  const importResult = await flags.imports.create({
@@ -469,8 +504,10 @@ The preview limits that apply to this workspace and how much of the counted ones
469
504
 
470
505
  | Status | Error class | Codes | When |
471
506
  |---|---|---|---|
507
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
472
508
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
473
509
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
510
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
474
511
 
475
512
  ```ts
476
513
  const flagsLimits = await flags.limits.retrieve();
@@ -494,10 +531,12 @@ Creates the project with the environments of `environment_preset` (default `dev_
494
531
  | Status | Error class | Codes | When |
495
532
  |---|---|---|---|
496
533
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is missing or invalid. |
534
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
497
535
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
498
536
  | 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `KEY_ALREADY_EXISTS`: another project has this name, or a key repeats in `environments` / `configs`. 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). |
499
537
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `LIMIT_EXCEEDED` | `LIMIT_EXCEEDED`: the workspace already has the maximum number of projects (`details`: `limit`, `max`, `current`). |
500
538
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
539
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
501
540
 
502
541
  ```ts
503
542
  const project = await flags.projects.create({ name: "Storefront" });
@@ -517,10 +556,12 @@ Deletes the project with all of its environments, configs, flags, segments, SDK
517
556
 
518
557
  | Status | Error class | Codes | When |
519
558
  |---|---|---|---|
559
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
520
560
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
521
561
  | 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
522
562
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `CONFIRMATION_REQUIRED` | `CONFIRMATION_REQUIRED`: `confirm` is missing or is not the exact project name. |
523
563
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
564
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
524
565
 
525
566
  ```ts
526
567
  await flags.projects.delete("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { confirm: "Storefront" });
@@ -542,8 +583,10 @@ The workspace's projects, oldest first, each with its environments and configs.
542
583
  | Status | Error class | Codes | When |
543
584
  |---|---|---|---|
544
585
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a bad cursor or a `limit` outside 1-100. |
586
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
545
587
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
546
588
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
589
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
547
590
 
548
591
  ```ts
549
592
  for await (const project of flags.projects.list()) {
@@ -564,9 +607,11 @@ The project with its environments and configs.
564
607
 
565
608
  | Status | Error class | Codes | When |
566
609
  |---|---|---|---|
610
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
567
611
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
568
612
  | 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
569
613
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
614
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
570
615
 
571
616
  ```ts
572
617
  const project = await flags.projects.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -587,10 +632,12 @@ Rename, describe or reorder the project. Only the fields you send change. Needs
587
632
  | Status | Error class | Codes | When |
588
633
  |---|---|---|---|
589
634
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid. |
635
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
590
636
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
591
637
  | 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
592
638
  | 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS` | `KEY_ALREADY_EXISTS`: another project has this name. |
593
639
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
640
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
594
641
 
595
642
  ```ts
596
643
  const project = await flags.projects.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { description: "string" });
@@ -613,9 +660,11 @@ The filtered history as a file, newest first, at most 50,000 rows, streamed. `cs
613
660
  | Status | Error class | Codes | When |
614
661
  |---|---|---|---|
615
662
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a bad filter or `format`, or `since` is not before `until`. |
663
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
616
664
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
617
665
  | 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
618
666
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
667
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
619
668
 
620
669
  ```ts
621
670
  const response = await flags.projects.changes.export("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -638,9 +687,11 @@ The history of a project, newest first: every write with who made it (user, API
638
687
  | Status | Error class | Codes | When |
639
688
  |---|---|---|---|
640
689
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a bad filter, cursor or `limit`, or `since` is not before `until`. |
690
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
641
691
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
642
692
  | 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
643
693
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
694
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
644
695
 
645
696
  ```ts
646
697
  for await (const change of flags.projects.changes.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f")) {
@@ -667,11 +718,13 @@ Adds a config to the project, with a published state in every environment. Each
667
718
  | Status | Error class | Codes | When |
668
719
  |---|---|---|---|
669
720
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is missing or invalid. |
721
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
670
722
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
671
723
  | 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
672
724
  | 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `KEY_ALREADY_EXISTS`: the project already has a config with this key. 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). |
673
725
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `LIMIT_EXCEEDED` | `LIMIT_EXCEEDED`: the project already has the maximum number of configs (`details`: `limit`, `max`, `current`). |
674
726
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
727
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
675
728
 
676
729
  ```ts
677
730
  const config = await flags.projects.configs.create("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { key: "checkout", name: "Checkout" });
@@ -693,9 +746,11 @@ The project's configs, in `ordinal` order.
693
746
  | Status | Error class | Codes | When |
694
747
  |---|---|---|---|
695
748
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a bad cursor or a `limit` outside 1-100. |
749
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
696
750
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
697
751
  | 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
698
752
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
753
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
699
754
 
700
755
  ```ts
701
756
  for await (const config of flags.projects.configs.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f")) {
@@ -722,11 +777,13 @@ Adds an environment to every config of the project. The key `production` starts
722
777
  | Status | Error class | Codes | When |
723
778
  |---|---|---|---|
724
779
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is missing or invalid. |
780
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
725
781
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
726
782
  | 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
727
783
  | 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `KEY_ALREADY_EXISTS`: the project already has an environment with this key. 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). |
728
784
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `LIMIT_EXCEEDED` | `LIMIT_EXCEEDED`: the project already has the maximum number of environments (`details`: `limit`, `max`, `current`). |
729
785
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
786
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
730
787
 
731
788
  ```ts
732
789
  const environment = await flags.projects.environments.create("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { key: "staging", name: "Staging" });
@@ -746,10 +803,12 @@ Deletes the environment with its values in every config, and its SDK keys. A pro
746
803
 
747
804
  | Status | Error class | Codes | When |
748
805
  |---|---|---|---|
806
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
749
807
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
750
808
  | 404 | `NotFoundError` | `NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `ENVIRONMENT_NOT_FOUND`: no such environment in this project. |
751
809
  | 409 | `ConflictError` | `CONFLICT`, `LAST_ENVIRONMENT` | `LAST_ENVIRONMENT`: this is the project's only environment. |
752
810
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
811
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
753
812
 
754
813
  ```ts
755
814
  await flags.projects.environments.delete("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -767,9 +826,11 @@ Every environment of the project, in `ordinal` order.
767
826
 
768
827
  | Status | Error class | Codes | When |
769
828
  |---|---|---|---|
829
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
770
830
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
771
831
  | 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
772
832
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
833
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
773
834
 
774
835
  ```ts
775
836
  const environmentList = await flags.projects.environments.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -785,9 +846,11 @@ Get an environment.
785
846
 
786
847
  | Status | Error class | Codes | When |
787
848
  |---|---|---|---|
849
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
788
850
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
789
851
  | 404 | `NotFoundError` | `NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `ENVIRONMENT_NOT_FOUND`: no such environment in this project. |
790
852
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
853
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
791
854
 
792
855
  ```ts
793
856
  const environment = await flags.projects.environments.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -808,9 +871,11 @@ Name, color, order, `protected` and `require_note`; the key never changes. Chang
808
871
  | Status | Error class | Codes | When |
809
872
  |---|---|---|---|
810
873
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid. |
874
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
811
875
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
812
876
  | 404 | `NotFoundError` | `NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `ENVIRONMENT_NOT_FOUND`: no such environment in this project. |
813
877
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
878
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
814
879
 
815
880
  ```ts
816
881
  const environment = await flags.projects.environments.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { color: "#e67700" });
@@ -834,11 +899,13 @@ A reusable set of ANDed user conditions that any config of the project can targe
834
899
  | Status | Error class | Codes | When |
835
900
  |---|---|---|---|
836
901
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is missing or invalid. |
902
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
837
903
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
838
904
  | 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
839
905
  | 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS`, `IDEMPOTENCY_KEY_REUSE`, `IDEMPOTENCY_IN_PROGRESS` | `KEY_ALREADY_EXISTS`: the project already has a segment with this key. 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). |
840
906
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `INVALID_TARGETING`, `LIMIT_EXCEEDED`, `CONFIDENTIAL_LIST_NOT_EDITABLE`, `NOTE_REQUIRED` | The conditions are invalid; `details.errors` lists every problem (`param`, `code`, `message`) and `code` is the first one: `INVALID_TARGETING` (shape, comparator or value), `LIMIT_EXCEEDED` (conditions, values or segments per project), `CONFIDENTIAL_LIST_NOT_EDITABLE` (`values_add` / `values_remove` on a list sent pre-hashed), or `NOTE_REQUIRED` (the segment is used in an environment that requires a `note`). |
841
907
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
908
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
842
909
 
843
910
  ```ts
844
911
  const segmentDetail = await flags.projects.segments.create("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {
@@ -867,9 +934,11 @@ The project's segments, oldest first, with `usage_count`.
867
934
  | Status | Error class | Codes | When |
868
935
  |---|---|---|---|
869
936
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a bad cursor or `limit`. |
937
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
870
938
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
871
939
  | 404 | `NotFoundError` | `NOT_FOUND`, `PROJECT_NOT_FOUND` | `PROJECT_NOT_FOUND`: no such project in this workspace. |
872
940
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
941
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
873
942
 
874
943
  ```ts
875
944
  for await (const segment of flags.projects.segments.list("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f")) {
@@ -894,10 +963,12 @@ Deletes an unused segment. Needs `flags.delete`.
894
963
 
895
964
  | Status | Error class | Codes | When |
896
965
  |---|---|---|---|
966
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
897
967
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
898
968
  | 404 | `NotFoundError` | `NOT_FOUND`, `SEGMENT_NOT_FOUND` | `SEGMENT_NOT_FOUND`: no such segment in this workspace. |
899
969
  | 409 | `ConflictError` | `CONFLICT`, `SEGMENT_IN_USE` | `SEGMENT_IN_USE`: a rule uses it (`details.used_by` lists where). |
900
970
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
971
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
901
972
 
902
973
  ```ts
903
974
  await flags.segments.delete("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -915,9 +986,11 @@ The segment with its conditions and every (setting, environment) that uses it (`
915
986
 
916
987
  | Status | Error class | Codes | When |
917
988
  |---|---|---|---|
989
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
918
990
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
919
991
  | 404 | `NotFoundError` | `NOT_FOUND`, `SEGMENT_NOT_FOUND` | `SEGMENT_NOT_FOUND`: no such segment in this workspace. |
920
992
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
993
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
921
994
 
922
995
  ```ts
923
996
  const segmentDetail = await flags.segments.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -935,10 +1008,12 @@ The cleartext of the segment's confidential lists, decrypted. Needs `flags.confi
935
1008
 
936
1009
  | Status | Error class | Codes | When |
937
1010
  |---|---|---|---|
1011
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
938
1012
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
939
1013
  | 404 | `NotFoundError` | `NOT_FOUND`, `SEGMENT_NOT_FOUND` | `SEGMENT_NOT_FOUND`: no such segment in this workspace. |
940
1014
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `CONFIDENTIAL_LIST_NOT_EDITABLE` | `CONFIDENTIAL_LIST_NOT_EDITABLE`: every confidential list was sent pre-hashed, so there is no cleartext. |
941
1015
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1016
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
942
1017
 
943
1018
  ```ts
944
1019
  const confidentialReveal = await flags.segments.revealConfidential("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -959,11 +1034,13 @@ Key, name, description or conditions; only the fields you send change. Edit a co
959
1034
  | Status | Error class | Codes | When |
960
1035
  |---|---|---|---|
961
1036
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid. |
1037
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
962
1038
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). A segment used in a protected environment also needs `flags.protected.update` on it. |
963
1039
  | 404 | `NotFoundError` | `NOT_FOUND`, `SEGMENT_NOT_FOUND` | `SEGMENT_NOT_FOUND`: no such segment in this workspace. |
964
1040
  | 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS`, `VERSION_CONFLICT` | `KEY_ALREADY_EXISTS`: the project already has a segment with this key; `VERSION_CONFLICT`: `version` is stale (`details.current_version`). |
965
1041
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `INVALID_TARGETING`, `LIMIT_EXCEEDED`, `CONFIDENTIAL_LIST_NOT_EDITABLE`, `NOTE_REQUIRED`, `CONFIG_TOO_LARGE` | The conditions are invalid; `details.errors` lists every problem (`param`, `code`, `message`) and `code` is the first one: `INVALID_TARGETING` (shape, comparator or value), `LIMIT_EXCEEDED` (conditions, values or segments per project), `CONFIDENTIAL_LIST_NOT_EDITABLE` (`values_add` / `values_remove` on a list sent pre-hashed), or `NOTE_REQUIRED` (the segment is used in an environment that requires a `note`). Publishing (every config that uses the segment): `CONFIG_TOO_LARGE` (a rendered config would exceed 1 MiB) or `LIMIT_EXCEEDED` with `details.limit: comparison_values_per_config`; the edit is not applied. |
966
1042
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1043
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
967
1044
 
968
1045
  ```ts
969
1046
  const segmentDetail = await flags.segments.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", {
@@ -996,10 +1073,12 @@ Deletes the setting and its values in every environment. Needs `flags.delete`.
996
1073
 
997
1074
  | Status | Error class | Codes | When |
998
1075
  |---|---|---|---|
1076
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
999
1077
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
1000
1078
  | 404 | `NotFoundError` | `NOT_FOUND`, `SETTING_NOT_FOUND` | `SETTING_NOT_FOUND`: no such setting in this workspace. |
1001
1079
  | 409 | `ConflictError` | `CONFLICT`, `SETTING_IN_USE` | `SETTING_IN_USE`: another setting uses it as a prerequisite (`details.used_by`). |
1002
1080
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1081
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
1003
1082
 
1004
1083
  ```ts
1005
1084
  await flags.settings.delete("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -1017,9 +1096,11 @@ The setting with its value and targeting in every environment, and what depends
1017
1096
 
1018
1097
  | Status | Error class | Codes | When |
1019
1098
  |---|---|---|---|
1099
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
1020
1100
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
1021
1101
  | 404 | `NotFoundError` | `NOT_FOUND`, `SETTING_NOT_FOUND` | `SETTING_NOT_FOUND`: no such setting in this workspace. |
1022
1102
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1103
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
1023
1104
 
1024
1105
  ```ts
1025
1106
  const settingDetail = await flags.settings.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -1040,12 +1121,13 @@ Key, name, description, hint, tags, lifecycle, owner or order; only the fields y
1040
1121
  | Status | Error class | Codes | When |
1041
1122
  |---|---|---|---|
1042
1123
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: a field is invalid. |
1124
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
1043
1125
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
1044
1126
  | 404 | `NotFoundError` | `NOT_FOUND`, `SETTING_NOT_FOUND` | `SETTING_NOT_FOUND`: no such setting in this workspace. |
1045
1127
  | 409 | `ConflictError` | `CONFLICT`, `KEY_ALREADY_EXISTS` | `KEY_ALREADY_EXISTS`: the config already has a setting with this key. |
1046
1128
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `SETTING_TYPE_IMMUTABLE`, `OWNER_NOT_A_MEMBER`, `CONFIG_TOO_LARGE`, `LIMIT_EXCEEDED` | `SETTING_TYPE_IMMUTABLE`: `type` differs from the current one; `OWNER_NOT_A_MEMBER`: `owner_id` is not a workspace member. Publishing: `CONFIG_TOO_LARGE` (the rendered config would exceed 1 MiB; `details.size_bytes`, `max_bytes`) or `LIMIT_EXCEEDED` with `details.limit: comparison_values_per_config` (over 20,000 comparison values in the config); the write is not applied. |
1047
1129
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1048
- | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE` | `SERVICE_UNAVAILABLE`: the member lookup for `owner_id` is unavailable; retry. |
1130
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | `SERVICE_UNAVAILABLE`: the member lookup for `owner_id` is unavailable; retry. Or `MANAGEMENT_UNAVAILABLE`: the whole management API is temporarily unavailable, for example while its database is unreachable; wait `Retry-After` seconds and retry. |
1049
1131
 
1050
1132
  ```ts
1051
1133
  const settingDetail = await flags.settings.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { description: "string" });
@@ -1068,11 +1150,13 @@ Replaces the value and the whole targeting (rules, flag-level split, split attri
1068
1150
  | Status | Error class | Codes | When |
1069
1151
  |---|---|---|---|
1070
1152
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: `version` or `note` is missing or invalid. |
1153
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
1071
1154
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). Value writes need `flags.value.update` on the environment and the setting, plus `flags.protected.update` in a protected environment. |
1072
1155
  | 404 | `NotFoundError` | `NOT_FOUND`, `SETTING_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `SETTING_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`. |
1073
1156
  | 409 | `ConflictError` | `CONFLICT`, `VERSION_CONFLICT` | `VERSION_CONFLICT`: the value changed since you read it (`details.current_version`, `updated_at`, `updated_by`). |
1074
1157
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `INVALID_VALUE`, `INVALID_TARGETING`, `SEGMENT_NOT_FOUND`, `CONFIDENTIAL_LIST_NOT_EDITABLE`, `PERCENTAGES_MUST_SUM_TO_100`, `PREREQUISITE_NOT_FOUND`, `PREREQUISITE_TYPE_MISMATCH`, `CIRCULAR_PREREQUISITE`, `LIMIT_EXCEEDED`, `NOTE_REQUIRED`, `CONFIG_TOO_LARGE` | The value or targeting is invalid; `details.errors` lists every problem (`param`, `code`, `message`) and `code` is the first one: `INVALID_VALUE` (type mismatch, over 100 KB, json that does not parse), `INVALID_TARGETING` (shape, comparator or comparison value), `SEGMENT_NOT_FOUND` (a segment condition names no segment of this project), `CONFIDENTIAL_LIST_NOT_EDITABLE` (`values_add` / `values_remove` on a list sent pre-hashed), `PERCENTAGES_MUST_SUM_TO_100`, `PREREQUISITE_NOT_FOUND`, `PREREQUISITE_TYPE_MISMATCH`, `CIRCULAR_PREREQUISITE` (`details.cycle` lists the keys), `LIMIT_EXCEEDED` (rules, conditions, values or prerequisite depth), or `NOTE_REQUIRED` (the environment requires a `note`). Publishing: `CONFIG_TOO_LARGE` (the rendered config would exceed 1 MiB; `details.size_bytes`, `max_bytes`) or `LIMIT_EXCEEDED` with `details.limit: comparison_values_per_config` (over 20,000 comparison values in the config); the write is not applied. |
1075
1158
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1159
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
1076
1160
 
1077
1161
  ```ts
1078
1162
  const settingValue = await flags.settings.values.replace("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { value: false, version: 3 });
@@ -1090,9 +1174,11 @@ The setting's value and targeting in one environment, with its `version`.
1090
1174
 
1091
1175
  | Status | Error class | Codes | When |
1092
1176
  |---|---|---|---|
1177
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
1093
1178
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
1094
1179
  | 404 | `NotFoundError` | `NOT_FOUND`, `SETTING_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `SETTING_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`. |
1095
1180
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1181
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
1096
1182
 
1097
1183
  ```ts
1098
1184
  const settingValue = await flags.settings.values.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -1110,10 +1196,12 @@ The cleartext of this value's confidential lists, decrypted. Needs `flags.confid
1110
1196
 
1111
1197
  | Status | Error class | Codes | When |
1112
1198
  |---|---|---|---|
1199
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
1113
1200
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
1114
1201
  | 404 | `NotFoundError` | `NOT_FOUND`, `SETTING_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `SETTING_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`. |
1115
1202
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `CONFIDENTIAL_LIST_NOT_EDITABLE` | `CONFIDENTIAL_LIST_NOT_EDITABLE`: every confidential list was sent pre-hashed, so there is no cleartext. |
1116
1203
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1204
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
1117
1205
 
1118
1206
  ```ts
1119
1207
  const confidentialReveal = await flags.settings.values.revealConfidential("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -1134,11 +1222,13 @@ The quick edits: `value` (the toggle), `percentage_attribute`, and `clear_rules:
1134
1222
  | Status | Error class | Codes | When |
1135
1223
  |---|---|---|---|
1136
1224
  | 400 | `BadRequestError` | `BAD_REQUEST`, `VALIDATION_ERROR` | `VALIDATION_ERROR`: nothing to change, or `version` is missing. |
1225
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
1137
1226
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). Value writes need `flags.value.update` on the environment and the setting, plus `flags.protected.update` in a protected environment. |
1138
1227
  | 404 | `NotFoundError` | `NOT_FOUND`, `SETTING_NOT_FOUND`, `ENVIRONMENT_NOT_FOUND` | `SETTING_NOT_FOUND` or `ENVIRONMENT_NOT_FOUND`. |
1139
1228
  | 409 | `ConflictError` | `CONFLICT`, `VERSION_CONFLICT` | `VERSION_CONFLICT`: the value changed since you read it (`details.current_version`, `updated_at`, `updated_by`). |
1140
1229
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY`, `INVALID_VALUE`, `INVALID_TARGETING`, `NOTE_REQUIRED`, `CONFIG_TOO_LARGE`, `LIMIT_EXCEEDED` | `INVALID_VALUE`, `INVALID_TARGETING` or `NOTE_REQUIRED`; `details.errors` lists each problem. Publishing: `CONFIG_TOO_LARGE` (the rendered config would exceed 1 MiB; `details.size_bytes`, `max_bytes`) or `LIMIT_EXCEEDED` with `details.limit: comparison_values_per_config` (over 20,000 comparison values in the config); the write is not applied. |
1141
1230
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1231
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
1142
1232
 
1143
1233
  ```ts
1144
1234
  const settingValue = await flags.settings.values.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", "3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { version: 3 });
@@ -1158,8 +1248,10 @@ Counts for the workspace: projects, configs, flags and settings, segments, chang
1158
1248
 
1159
1249
  | Status | Error class | Codes | When |
1160
1250
  |---|---|---|---|
1251
+ | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing, expired or invalid bearer token (`UNAUTHORIZED`). Send a workspace API key or a platform session token as `Authorization: Bearer <token>`. |
1161
1252
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | The caller lacks the action this route needs (`message` names it), or the workspace has not enabled Flags (`SERVICE_NOT_ENABLED`). |
1162
1253
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1254
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
1163
1255
 
1164
1256
  ```ts
1165
1257
  const flagsStats = await flags.stats.retrieve();
@@ -1198,6 +1290,7 @@ Deliveries are signed with the Standard Webhooks headers `webhook-id`, `webhook-
1198
1290
  | 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). |
1199
1291
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY` | The URL points at a private, loopback or internal address. |
1200
1292
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1293
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
1201
1294
 
1202
1295
  ```ts
1203
1296
  const webhookEndpoint = await flags.webhooks.endpoints.create({ url: "https://api.acme.com/webhooks" });
@@ -1220,6 +1313,7 @@ Queued retries are dropped. Its past attempts stay in the event log until the ev
1220
1313
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `flags.webhook.read` (reads) or `flags.webhook.manage` (changes, Send test, replay), or Flags is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
1221
1314
  | 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
1222
1315
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1316
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
1223
1317
 
1224
1318
  ```ts
1225
1319
  await flags.webhooks.endpoints.delete("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -1243,6 +1337,7 @@ At most 10, so this is always one page. Signing secrets are never returned here,
1243
1337
  | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
1244
1338
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `flags.webhook.read` (reads) or `flags.webhook.manage` (changes, Send test, replay), or Flags is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
1245
1339
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1340
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
1246
1341
 
1247
1342
  ```ts
1248
1343
  for await (const endpoint of flags.webhooks.endpoints.list()) {
@@ -1267,6 +1362,7 @@ The endpoint's URL, subscription, on/off state, failure streak and the last 4 ch
1267
1362
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `flags.webhook.read` (reads) or `flags.webhook.manage` (changes, Send test, replay), or Flags is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
1268
1363
  | 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
1269
1364
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1365
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
1270
1366
 
1271
1367
  ```ts
1272
1368
  const webhookEndpoint = await flags.webhooks.endpoints.retrieve("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f");
@@ -1293,6 +1389,7 @@ For `grace_hours` (default 24) the previous secret keeps signing too: `webhook-s
1293
1389
  | 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
1294
1390
  | 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). |
1295
1391
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1392
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
1296
1393
 
1297
1394
  ```ts
1298
1395
  const webhookEndpoint = await flags.webhooks.endpoints.rotateSecret("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { grace_hours: 24 });
@@ -1319,6 +1416,7 @@ Delivers the catalogue example of `event_type`, signed like any delivery, with `
1319
1416
  | 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_ENDPOINT_NOT_FOUND` | No such endpoint here (`WEBHOOK_ENDPOINT_NOT_FOUND`). |
1320
1417
  | 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). |
1321
1418
  | 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
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
1322
1420
 
1323
1421
  ```ts
1324
1422
  const webhookDeliveryAttempt = await flags.webhooks.endpoints.test("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { event_type: "config.published" });
@@ -1346,6 +1444,7 @@ Only the fields sent change. `enabled: true` (or a new URL) also clears an autom
1346
1444
  | 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). |
1347
1445
  | 422 | `UnprocessableEntityError` | `UNPROCESSABLE_ENTITY` | The new URL points at a private, loopback or internal address. |
1348
1446
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1447
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
1349
1448
 
1350
1449
  ```ts
1351
1450
  const webhookEndpoint = await flags.webhooks.endpoints.update("3f0c3c1e-8a2b-4c55-9d3f-0a1b2c3d4e5f", { config_id: "9b2f6c1e-0d6a-4a63-9a43-2f1c3e4d5a6b" });
@@ -1368,6 +1467,7 @@ Each type with a plain description, its group and an example `data` object (what
1368
1467
  | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
1369
1468
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `flags.webhook.read` (reads) or `flags.webhook.manage` (changes, Send test, replay), or Flags is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
1370
1469
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1470
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
1371
1471
 
1372
1472
  ```ts
1373
1473
  const webhookEventTypeList = await flags.webhooks.eventTypes.list();
@@ -1394,6 +1494,7 @@ Every event logged while at least one endpoint existed, with the latest state pe
1394
1494
  | 401 | `AuthenticationError` | `UNAUTHORIZED` | Missing or invalid bearer token. |
1395
1495
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `flags.webhook.read` (reads) or `flags.webhook.manage` (changes, Send test, replay), or Flags is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
1396
1496
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1497
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
1397
1498
 
1398
1499
  ```ts
1399
1500
  for await (const event of flags.webhooks.events.list()) {
@@ -1423,6 +1524,7 @@ Same body and `webhook-id`, freshly signed, to every switched-on endpoint that r
1423
1524
  | 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`). |
1424
1525
  | 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). |
1425
1526
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1527
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
1426
1528
 
1427
1529
  ```ts
1428
1530
  const webhookEventReplay = await flags.webhooks.events.replay("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");
@@ -1445,6 +1547,7 @@ The event as it was sent (`type`, `data`) and every delivery attempt to every en
1445
1547
  | 403 | `PermissionDeniedError` | `FORBIDDEN`, `SERVICE_NOT_ENABLED` | Caller lacks `flags.webhook.read` (reads) or `flags.webhook.manage` (changes, Send test, replay), or Flags is not enabled for the workspace (`SERVICE_NOT_ENABLED`). |
1446
1548
  | 404 | `NotFoundError` | `NOT_FOUND`, `WEBHOOK_EVENT_NOT_FOUND` | No such event here (`WEBHOOK_EVENT_NOT_FOUND`); events are kept for 30 days. |
1447
1549
  | 429 | `RateLimitError` | `RATE_LIMITED` | More than 20 requests per second or 600 per minute from this client IP (`RATE_LIMITED`); wait `Retry-After` seconds. |
1550
+ | 503 | `InternalServerError` | `SERVICE_UNAVAILABLE`, `MANAGEMENT_UNAVAILABLE` | The management API is temporarily unavailable (`MANAGEMENT_UNAVAILABLE`), for example while its database is unreachable. Wait `Retry-After` seconds and retry; SDK config delivery keeps serving. |
1448
1551
 
1449
1552
  ```ts
1450
1553
  const webhookEventDetail = await flags.webhooks.events.retrieve("3f0c1a2b-4c5d-4e6f-8a9b-0c1d2e3f4a5b");