Skip to main content

​
Overview

The Boomerang Developer API uses standard HTTP status codes together with structured error codes and a consistent JSON error format. This page covers:
  • Common HTTP status codes
  • The JSON error shape
  • Core error codes, including rate-limit errors
  • How to use trace_id when investigating failures
Endpoint-specific codes and examples are documented in the API reference.

​
Standard HTTP status codes

HTTP statusMeaningRemediation
200OKNone.
400Bad RequestCorrect the request body or query parameters.
401UnauthorisedFix token, header format, or expiry.
403ForbiddenCheck server ownership and permissions.
404Not FoundCheck the URL path and identifiers.
409ConflictResolve current resource state, then retry.
422Unprocessable EntityCorrect field values and constraints.
429Too Many RequestsReduce request rate, use X-RateLimit-* and X-Credits-Remaining headers, and apply back-off logic.
500Internal Server ErrorRetry later; if persistent, contact Boomerang Customer Service with trace_id.
503Service UnavailableRetry with back-off; if persistent, contact Boomerang Customer Service with trace_id.
For repeated 5xx responses, contact Boomerang Customer Service and include the trace_id from the error body.

​
Error response format

All non-2xx responses return a JSON body with a consistent structure. 
{
  "status": "RESOURCE_NOT_FOUND",
  "code": 2404,
  "http_status": 404,
  "method": "GET",
  "path": "/v1/example/resource",
  "timestamp": 1763205835591,
  "trace_id": "0c0f6a6b-1e7a-4ca2-9f80-13c1b4e2c7f2",
  "details": {
    "message": "The requested resource could not be found.",
    "hint": "Verify the resource identifier and try again."
  }
}
Field semantics:
  • status – machine-readable status string (for example, RESOURCE_NOT_FOUND).
  • code – four-digit error code, independent of the HTTP status.
  • http_status – HTTP status code returned for this response.
  • method – HTTP method used (for example, GET, POST).
  • path – request path that generated the error.
  • timestamp – Unix epoch timestamp in milliseconds.
  • trace_id – correlation identifier for this request; include this when contacting Boomerang about an issue.
  • details – object containing human-oriented context:
    • details.message – human-readable explanation suitable for logs and dashboards.
    • details.hint – short remediation suggestion that can be surfaced to operators.

​
Error codes

Error codes are four-digit integers organised by category:
  • 1xxx – Validation and request shape issues
  • 2xxx – Authentication and authorisation failures
  • 3xxx – Resource existence and state conflicts
  • 4xxx – Rate limits and capacity issues
  • 5xxx – Internal and unexpected errors
  • 6xxx – Successful operations
Core codes:
CodeStatusDescription
1001VALIDATION_FAILEDRequest body or parameters invalid
1002SEMANTIC_ERRORSemantically invalid request
2001AUTHENTICATION_FAILEDMissing, invalid, or malformed auth token
2002NOT_AUTHORISEDToken is valid but not permitted
2404RESOURCE_NOT_FOUNDRequested resource does not exist
3001RESOURCE_CONFLICTRequest conflicts with current resource
4001RATE_LIMIT_HOURLYPer-key hourly rate limit exceeded
4002USAGE_EXHAUSTEDNo remaining monthly quota or credits for the server
5001INTERNAL_ERRORUnexpected server-side error
5002SERVICE_UNAVAILABLEService temporarily unavailable or undergoing maintenance
6200SUCCESSRequest completed successfully
Additional, endpoint-specific codes are documented in the API reference.

​
Rate-limiting errors

When rate limits or usage limits are reached, the API returns HTTP 429 Too Many Requests with an error body in the standard format. Representative scenarios:
  • Hourly limit exceeded for a key
    • HTTP status: 429
    • Error code: 4001 (RATE_LIMIT_HOURLY)
    • Behaviour: further requests from this key are rejected until the sliding 60-minute window allows more calls.
    • Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
    • Typical details.hint: indicates that the hourly limit for this key has been reached and when it will reset.
  • All quota and credits exhausted for a server
    • HTTP status: 429
    • Error code: 4002 (USAGE_EXHAUSTED)
    • Behaviour: further successful requests are rejected until the next monthly reset or additional credits are purchased.
    • Headers: X-Credits-Remaining (zero or very low) and possibly X-RateLimit-* indicating that usage is blocked by quota.
    • Typical details.hint: indicates that the server has no remaining monthly quota or credits and points to upgrading or purchasing credits.
In all rate-limit cases, clients should honour the headers:
  • X-RateLimit-Limit – maximum allowed in the current window for this key.
  • X-RateLimit-Remaining – remaining requests in the current window for this key.
  • X-RateLimit-Reset – Unix epoch timestamp when the window resets.
  • X-Credits-Remaining – total remaining credit-pack balance for the server (if applicable).

​
Handling errors in clients

Client implementations should:
  • Use the HTTP status as the primary success/failure signal.
  • Use code and status for programmatic handling and branching.
  • Use details.message and details.hint for human-readable diagnostics.
  • Log trace_id and timestamp for every non-2xx response.
  • On 429 responses:
    • Respect X-RateLimit-Reset and back off instead of retrying in a tight loop.
    • Adjust request patterns (for example, batch and spread work) to reduce pressure.
For repeated 5xx responses or behaviour that does not match the documentation, contact Boomerang Customer Service and include trace_id, status, code, and the relevant request context.