Error handling

Handle failures predictably and preserve diagnostic context.

Northstar uses standard HTTP status codes and a consistent JSON error envelope.

Error response

json

{
  "error": {
    "code": "invalid_region",
    "message": "The selected region is not available.",
    "field": "region"
  },
  "request_id": "req_01J8ZA8E1T"
}

Common status codes

Status	Meaning	Recommended action
400	Invalid request	Correct the submitted fields
401	Invalid authentication	Replace or rotate the token
403	Missing scope	Grant only the required scope
404	Resource not found	Verify the identifier and workspace
409	State conflict	Refresh the resource before retrying
429	Rate limit exceeded	Wait for retry-after
5xx	Temporary service failure	Retry with exponential backoff

Retry safely

Retry connection errors, 429, and transient 5xx responses. Do not automatically retry validation or authorization failures.

Use an idempotency key for create and action endpoints. Reusing the same key returns the original result instead of repeating the operation.

Always log the request_id, endpoint, status, and error code. Never log bearer tokens or complete sensitive payloads.

Webhooks

Deployment