Nexus Errors

Common error codes returned by Nexus project management endpoints.

Error Response Format

All errors follow this structure:

{
  "error": {
    "code": "validation_error",
    "message": "Project name must be between 1 and 100 characters"
  }
}

Error Codes

validation_error (400)

Invalid request parameters or body.

HTTP Status: 400 Bad Request

Common causes:

  • Project name too short (< 1 char) or too long (> 100 chars)
  • Description exceeds 500 characters
  • Missing required name field in POST /v1/projects
  • Invalid JSON in request body

Example response:

{
  "error": {
    "code": "validation_error",
    "message": "Project name must be between 1 and 100 characters"
  }
}

Fix: Validate request parameters match schema requirements.

unauthorized (401)

Missing or invalid API key.

HTTP Status: 401 Unauthorized

Common causes:

  • No Authorization header
  • Malformed bearer token
  • Revoked or expired API key
  • Invalid key format

Example response:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Fix: Include valid API key in Authorization: Bearer YOUR_KEY header.

forbidden (403)

Operation not allowed.

HTTP Status: 403 Forbidden

Common causes:

  • Attempting to delete the default project when it’s the only active project
  • Accessing a project that belongs to a different user
  • Insufficient permissions for the operation

Example response:

{
  "error": {
    "code": "forbidden",
    "message": "Cannot delete default project. Create another project first."
  }
}

Fix: Ensure you have at least one non-default project before deleting the default project.

not_found (404)

Project doesn’t exist or has been deleted.

HTTP Status: 404 Not Found

Common causes:

  • Project ID doesn’t exist
  • Project was soft-deleted
  • Typo in project ID
  • Wrong project ID in path parameter

Example response:

{
  "error": {
    "code": "not_found",
    "message": "Project not found"
  }
}

Fix: Verify project ID exists via GET /v1/projects list endpoint.

conflict (409)

Slug collision during project creation.

HTTP Status: 409 Conflict

Common causes:

  • Project with same slug already exists
  • Auto-generated slug collides after 10 attempts with -N suffix

Example response:

{
  "error": {
    "code": "conflict",
    "message": "Project slug 'production' already exists"
  }
}

Resolution: Nexus automatically resolves collisions by appending -N suffix (production-2, production-3). After 10 attempts, falls back to UUID. This error is rare and typically self-healing.

Fix: Retry request — Nexus will auto-resolve with unique slug.

rate_limit_exceeded (429)

Too many requests in a short time window.

HTTP Status: 429 Too Many Requests

Common causes:

  • Polling project overview too frequently
  • Batch creating many projects rapidly
  • Exceeding per-user rate limits

Example response:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 60 seconds."
  }
}

Fix: Implement exponential backoff. Check Retry-After header for wait time.

Common Error Scenarios

Creating project with duplicate name

Scenario: Two projects can have the same name (names are not unique). Only slugs must be unique.

Behavior: Both projects created successfully with different slugs (production, production-2).

No error — this is expected behavior.

Deleting default project as only project

Error: forbidden (403)

Scenario:

curl -X DELETE "https://api.solenoid.systems/v1/projects/proj_default..." \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "error": {
    "code": "forbidden",
    "message": "Cannot delete default project. Create another project first."
  }
}

Fix: Create at least one other active project, then you can delete the default project.

Accessing deleted project

Error: not_found (404)

Scenario: Project was soft-deleted via DELETE /v1/projects/:id. All subsequent operations return 404.

Response:

{
  "error": {
    "code": "not_found",
    "message": "Project not found"
  }
}

Fix: Deleted projects are not restorable. Create a new project instead.

Exceeding project limit

No limit — Projects are unlimited on all tiers. This error does not exist for Nexus.

Debugging Tips

  1. Check project ID format — Must start with proj_ followed by alphanumeric string
  2. Verify project exists — Use GET /v1/projects to list all active projects
  3. Check deletion status — Deleted projects return 404 on all operations
  4. Inspect API key scopes — Some operations require specific scopes (future enhancement)
  5. Monitor rate limits — Implement exponential backoff for all list operations

Next steps