What the Attachment Manager REST API returns when a call fails, the limits that apply, and how to fix the most common problems. For setup see REST API — setup and usage; for the endpoints see REST API reference.
Errors and retries
Every error from the app has the same shape:
{
"error": {
"code": "NOT_FOUND",
"message": "attachment 10999 not found",
"details": {}
},
"inv": "EXAMPLE_INVOCATION_ID"
}
Branch on error.code rather than error.message. details is optional. Keep inv for support. Gateway errors from Atlassian can have a different response shape.
|
HTTP / code |
Meaning and action |
|---|---|
|
400 VALIDATION |
Invalid JSON, parameter, ID, name, range, cursor or limit. Fix the request before retrying. |
|
401 (gateway) |
Missing, expired or invalid token. Refresh access and retry. |
|
403 FORBIDDEN |
Token owner lacks a required Jira permission, such as Edit Issues. Check the project permission scheme. |
|
403 EDITION_REQUIRED |
The REST API is part of the Advanced edition of Attachment Manager and the site is on another edition. A site admin changes the edition in Atlassian Administration. Do not retry until then. |
|
403 (gateway) |
API is disabled or scopes are missing. Check the site toggle, app environment, read:forge-app:jira, custom scopes and sns; consent again after adding scopes. |
|
404 NOT_FOUND |
Attachment/label does not exist or is not visible/indexed. Check IDs, project tracking, issue security and recent-upload indexing. |
|
404 (gateway route) |
Check base URL, HTTP method and /v1 path. PATCH is not one of the supported operations. |
|
409 LABEL_NAME_EXISTS |
Concurrent creation of the same name. Retry once so the name resolves to the existing label. |
|
429 UPSTREAM_RATE_LIMITED |
Jira limited the request. Wait the Retry-After seconds before retrying. |
|
429 (platform) |
Use exponential backoff; honour Retry-After when supplied. |
|
500 INTERNAL / SQL_ERROR; 502 UPSTREAM_ERROR |
Retry with bounded backoff. Contact support with inv if persistent. |
|
503 MIGRATION_IN_PROGRESS |
Setup or upgrade is still running. Wait the Retry-After seconds (60) before retrying. |
|
504 TIMEOUT |
Retry or narrow the search with projects and filters. |
Repeating an identical POST, PUT or DELETE is idempotent with respect to the intended label state. Avoid unbounded retry loops; PUT still replaces the complete set, so coordinate concurrent editors when that matters.
Limits and freshness
The limits come in three kinds. The limits of the app itself, such as folder sizes and bulk actions in the Jira screens, are on Limits.
For each request
These apply to one call. There is no running total: send another request to go further.
|
Limit |
Value |
|---|---|
|
Labels in one POST (add) request |
1 to 50 |
|
Labels in one PUT (replace) request |
0 to 50. An empty list removes every label from the attachment. |
|
Rows in one page of search results |
1 to 100, 50 by default. Follow nextCursor for the next page. |
|
Projects in one search |
Up to 50 projectId values. When none are given, the first 50 projects the caller can browse. |
|
Shortest file name query (q) |
2 characters |
In total, and each day
These are shared with the Jira screens. A request that would go past one is refused with 400 VALIDATION.
|
Limit |
Value |
|---|---|
|
Different labels in the Jira site (the whole label catalogue) |
1,000 at any one time. Delete or merge labels to make room. |
|
Letters in a label name |
100 |
|
New labels one account can create |
50 a day, counted per UTC calendar day. This includes labels the API creates because a name in a write request did not exist yet. Jira administrators have no daily limit. |
|
Labels on one attachment |
No limit |
Tokens and request rate
|
Limit |
Value |
|---|---|
|
Access token |
Lasts 1 hour. Reuse it across requests and renew it with the refresh token. |
|
Refresh token |
Changes on each use and expires after 90 days without use. |
|
Number of requests over time |
Set by Atlassian, not by the app, and not published while Forge app REST APIs are in Preview. Handle 429 and Retry-After instead of relying on a fixed quota. |
Freshness
New uploads are usually indexed within seconds. Label changes are available through this API when the write returns; catalogue usage counts update later. The REST API is part of the Advanced edition of Attachment Manager; there is no separate API licence beyond that.
Troubleshooting
-
“REST APIs are not allowed: installationConfig is missing”: enable App REST APIs for this exact app/environment and site.
-
“Missing required scopes”: preserve the console-generated sns parameter, add the missing custom/product scopes, and obtain fresh consent.
-
Search is incomplete: specify projectId batches, check the case of q, verify tracked projects, and follow nextCursor until null.
-
Every call returns 403 EDITION_REQUIRED: the site is not on the Advanced edition. On such sites the REST API tab of the app settings shows an upgrade notice instead of the setup steps.
-
A visible Jira attachment returns 404: verify its project is tracked and allow time for indexing; also check the consenting account’s access.
When contacting support, provide the method and path, status/error code, timestamp and inv. Remove access tokens, refresh tokens and client secrets from examples.
Versioning and changelog
The version is part of the path: /v1. Clients should tolerate additional optional response fields and new error codes. Breaking changes use a new version path.
|
Date |
Change |
|---|---|
|
14 September 2026 |
v1 released: label catalogue; read, add, replace and remove attachment labels; attachment search. |
|
15 September 2026 |
The API becomes an Advanced-edition feature: new error code EDITION_REQUIRED (403) for sites on another edition. |