Errors

Use the HTTP status code to check whether an Insuredspeaks API request succeeded. API error responses include success: false and a message explaining the failure.

Error response

For example, a portfolio list request with page=0 returns 400:

Invalid pagination parameters

{
  "success": false,
  "message": "Invalid pagination parameters"
}

Name
success
Type
boolean
Description
Always false for an API error response.
Name
message
Type
string
Description
A description of the failure. Use the HTTP status for control flow rather than matching message text.
Name
error
Type
string | object
Description
Optional additional details. Rate-limit responses include a structured object; some policy failures include a string. Do not assume this field is present or has the same shape on every endpoint.

The API does not define a universal error-type field or a documentation URL in its error responses. An unknown route or a failure at a hosting proxy may return a non-JSON response; check the content type before parsing the body.

Status codes

Successful reads, updates, and deletions normally return 200; successful portfolio, profile, and holding creation returns 201. Common failure responses are:

Status	Meaning	What to do
`400`	Invalid request fields, IDs, JSON, pagination, or conflicting authentication credentials. Policy search also requires a nonblank `q`.	Check the endpoint's inputs and correct the request.
`401`	Missing, invalid, inactive, or expired credentials.	Check your API key or refresh your access token. See Authentication.
`404`	The requested resource was not found. Portfolio resources also return this when they are inaccessible to the caller.	Verify the resource ID and the account making the request.
`409`	A portfolio operation conflicts with existing data or a resource constraint.	Read the current resource and resolve the conflict before retrying.
`413`	The request body is too large.	Reduce the request payload.
`429`	The API-key rate limit has been exceeded.	Wait until the rate-limit window resets.
`500`	The server could not complete the request.	Retry reads with a delay. For writes, check the resource state before retrying.
`503`	A required service is unavailable.	Wait and retry reads with a delay; check the resource state before retrying writes.

Rate limits

Requests authenticated with an API key are rate-limited. Once the key is validated and the rate limit is checked, the API sets these response headers:

Name
X-RateLimit-Limit
Type
integer
Description
The request limit for the current window.
Name
X-RateLimit-Remaining
Type
integer
Description
The number of requests remaining in the current window.
Name
X-RateLimit-Reset
Type
integer
Description
The time the window resets, as Unix seconds.

A 429 response includes error.code set to RATE_LIMIT_EXCEEDED, together with limit, current, and reset_at. The reset time in the body is an ISO 8601 string. These example limits are illustrative; use the values returned by your request.

Rate limit exceeded

{
  "success": false,
  "message": "Rate limit exceeded. Please try again later.",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "limit": 100,
    "current": 101,
    "reset_at": "2026-10-28T10:01:00.000Z"
  }
}

Troubleshooting

Check the method, path, credentials, and request body against the endpoint reference. If a failure persists, include the HTTP status, error message, endpoint, and request time when contacting support. Remove API keys, access tokens, and personal data from any shared request or response.