I'mBoard API Docs

All errors follow a consistent envelope format with machine-readable codes.

Error Envelope

Every error response returns the same shape:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description.",
    "status": 400,
    "requestId": "req_a1b2c3d4e5f6a7b8",
    "details": null
  }
}

Field	Type	Description
`code`	string	Machine-readable error code (see table below)
`message`	string	Human-readable description of the error
`status`	integer	HTTP status code
`requestId`	string or null	Unique request identifier for tracing
`details`	object or null	Structured details when available (e.g., field-level validation errors)

Error Codes

Code	HTTP Status	Description
`UNAUTHENTICATED`	401	No token provided or token format invalid
`INVALID_API_TOKEN`	401	Token expired, revoked, or not found
`ACCOUNT_SUSPENDED`	403	Account suspended by an administrator
`ACCOUNT_INACTIVE`	403	Account is inactive
`BILLING_RESTRICTED`	403	Billing issue restricts access
`FORBIDDEN`	403	Insufficient permissions for this resource
`RESOURCE_NOT_FOUND`	404	Resource does not exist or is not accessible
`INVALID_REQUEST_BODY`	400	Request body failed validation
`INVALID_QUERY_PARAMETER`	400	One or more query parameters are invalid
`METHOD_NOT_ALLOWED`	405	HTTP method not supported for this endpoint
`RATE_LIMITED`	429	Too many requests — slow down
`INTERNAL_ERROR`	500	Unexpected server error

Validation Errors

When a request fails validation, the details field may contain structured information about which fields failed:

{
  "error": {
    "code": "INVALID_QUERY_PARAMETER",
    "message": "One or more query parameters are invalid.",
    "status": 400,
    "requestId": "req_a1b2c3d4e5f6a7b8",
    "details": {
      "fields": {
        "limit": "Must be an integer between 1 and 100",
        "sort": "Invalid sort field. Allowed: createdAt, updatedAt"
      }
    }
  }
}

Rate Limiting

The API enforces rate limits per 5-minute sliding window:

Context	Limit	Key
Authenticated (API token)	300 requests / 5 minutes	Per token
Unauthenticated	60 requests / 5 minutes	Per IP address

Rate Limit Headers

Every response includes rate limit headers so you can track your usage:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp (seconds) when the window resets
`Retry-After`	Seconds to wait before retrying (only on `429` responses)

Rate Limit Example

When you exceed the limit, the API returns 429:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please try again later.",
    "status": 429,
    "requestId": "req_x9y8z7w6v5u4t3s2",
    "details": null
  }
}

Best practices:

Check X-RateLimit-Remaining before making requests
When you receive a 429, wait for the number of seconds in the Retry-After header
Implement exponential backoff for retry logic

Troubleshooting

401 Errors

Verify the Authorization header format: Bearer imb_pat_...
Check that the token has not expired or been revoked
Confirm the token exists in Account > API Access

403 Errors

Verify the authenticated user has access to the target board
Check billing status if you see BILLING_RESTRICTED
ACCOUNT_SUSPENDED and ACCOUNT_INACTIVE indicate account-level issues — contact support

404 Errors

Verify the resource ID is correct
Confirm the authenticated user has access to the parent board
The API returns 404 (not 403) for resources the user cannot access — this prevents leaking resource existence

429 Errors

Read the Retry-After header and wait before retrying
Check X-RateLimit-Reset to know when your window resets
Reduce request frequency or implement request batching where possible

Errors

On this page