Errors

The OpsFusion API uses standard HTTP status codes. This page lists what each one means and what usually causes it.

Status Codes

Status	Meaning
200 OK	The request succeeded
400 Bad Request	The request is invalid
401 Unauthorized	The Authorization header is missing
403 Forbidden	The request is denied
404 Not Found	The thing you tried to change doesn’t exist
409 Conflict	The request conflicts with the current state
415 Unsupported Media Type	The Content-Type: application/json header is missing on a request with a body
429 Too Many Requests	An alert or notification quota is reached
500 Internal Server Error	Something went wrong on our side

Error Body

Errors return a JSON body with a message field. Use the status code for logic, and the message for logs and humans.

For most errors, the message starts with the error type, followed by a detail. For example, a 409 message starts with conflict. Other error responses may include extra fields. Don’t rely on them.

Common Causes

401 Unauthorized

• The Authorization header is missing or empty.

403 Forbidden

• The key is incorrect, unknown, or deleted.
• The key belongs to a different account than the one in the URL.
• The account is inactive, or its trial has expired.
• The key’s roles don’t allow the endpoint. See Authentication and Roles.
• You tried something that isn’t allowed, such as deleting the Default team, deleting the account owner, or acknowledging an alert that belongs to another team.
• The path is wrong. A path that doesn’t exist also returns 403.

400 Bad Request

• The JSON body is malformed, has a missing required field, or has a field that isn’t allowed.
• A value is outside its limits, such as a title that’s too long.
• A query parameter is invalid, such as a non-numeric ID, start, or end.
• A timezone isn’t a valid IANA timezone.

404 Not Found

PATCH and DELETE requests return 404 when the team, alert, user, or other target doesn’t exist.

409 Conflict

• You tried to create something that already exists, such as an invite for an email that already has one.
• You reached a limit, such as the maximum number of teams or open invites.
• The state doesn’t allow the change. For example, you tried to acknowledge a closed alert, add a user who is already a team member, or remove a member who is still assigned to a rotation, escalation, or override.

429 Too Many Requests

A 429 means a monthly quota for your account is reached, with a message such as alert quota reached (N) or notification quota reached (N). These errors only come from the push endpoints. Retrying won’t help until the quota resets.

500 Internal Server Error

• Something failed on our side. Retry with exponential backoff.

If a 500 persists, contact support@opsfusion.cloud.

Retrying

Status	Retry?
400, 401, 403, 404, 409, 415	No. Fix the request first.
429	Not until your quota resets
500	Yes, with exponential backoff