Skip to content

Errors

Purpose

Describe how the Get2Dial API signals errors so clients can handle them consistently.

Overview

Errors use the same envelope as success responses, with status: "error" and a human-readable message. The HTTP status code carries the machine-readable meaning; data is omitted.

{
  "status": "error",
  "message": "invalid credentials"
}

Status codes

Code	Meaning	Typical cause
`400 Bad Request`	Malformed request	Invalid JSON, a missing required field, or an unknown field (bodies reject unknown fields)
`401 Unauthorized`	Not authenticated	Missing/invalid/expired token; wrong credentials on login
`403 Forbidden`	Authenticated but not allowed	Insufficient role/capability; disabled or temporarily locked account
`404 Not Found`	No such resource	Unknown id, or a resource in another tenant
`409 Conflict`	State conflict	Uniqueness violation, or an optimistic-concurrency version mismatch
`500 Internal Server Error`	Server fault	Unexpected failure; safe to retry idempotent reads

Examples

# Missing token → 401
curl -i https://api.get2dial.com/api/v1/auth/me
# HTTP/1.1 401 Unauthorized
# {"status":"error","message":"missing or invalid authorization header"}

# Unknown field in body → 400 (bodies reject unknown fields)
curl -i -X POST https://api.get2dial.com/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"a@b.com","password":"x","tenant":"oops"}'
# HTTP/1.1 400 Bad Request
# {"status":"error","message":"invalid request body"}

Notes

Authentication failures are deliberately generic (invalid credentials) to avoid revealing whether an email or workspace exists.
A 403 with an account temporarily locked message means the failed-login lockout (10 attempts → 15 minutes) is in effect — back off and retry later.
Cross-tenant access to a resource you can’t see generally returns 404/403 rather than confirming the resource exists.